diff --git a/.gitignore b/.gitignore
index 1eb0d79c..aea71a6e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,7 +49,7 @@ app/config/settings.json
 **/CONVERSATION_HISTORY.md
 **/EVENT_UNPROCESSED.md
 **/EVENT.md
-**/TASK_HISTORY.md
+agent_file_system/TASK_HISTORY.md
 **/USER.md
 **/onboarding_config.json
 **/config.json
diff --git a/agent_core/core/impl/action/manager.py b/agent_core/core/impl/action/manager.py
index d17ad889..b038c61c 100644
--- a/agent_core/core/impl/action/manager.py
+++ b/agent_core/core/impl/action/manager.py
@@ -387,13 +387,23 @@ async def execute_action(
 
         logger.debug(f"Persisting final state for action {action.name}...")
 
-        # Update action count in state
-        state = get_state_or_none()
-        if state:
-            state.set_agent_property(
+        # Update action count on the per-task StateSession (per-task counter).
+        # Falls back to the global state provider when no session is registered
+        # (e.g. transient/conversation-mode actions before any task is created).
+        from agent_core.core.state.session import StateSession
+        session = StateSession.get_or_none(session_id) if session_id else None
+        if session is not None:
+            session.agent_properties.set_property(
                 "action_count",
-                state.get_agent_property("action_count", 0) + 1
+                session.agent_properties.get_property("action_count", 0) + 1,
             )
+        else:
+            state = get_state_or_none()
+            if state:
+                state.set_agent_property(
+                    "action_count",
+                    state.get_agent_property("action_count", 0) + 1
+                )
 
         # Call on_action_end hook if provided
         if self._on_action_end:
diff --git a/agent_core/core/impl/action/router.py b/agent_core/core/impl/action/router.py
index a9c291d5..1bd5d11a 100644
--- a/agent_core/core/impl/action/router.py
+++ b/agent_core/core/impl/action/router.py
@@ -98,15 +98,12 @@ async def select_action(
         # Base conversation mode actions
         base_actions = ["send_message", "task_start", "ignore"]
 
-        # Dynamically add messaging actions for connected platforms
+        # Dynamically add messaging actions for connected platforms.
+        # Curation (which actions match which integration) lives in the host —
+        # the package only reports which platforms are currently connected.
         try:
-            from app.external_comms.integration_discovery import (
-                get_connected_messaging_platforms,
-                get_messaging_actions_for_platforms,
-            )
-            connected_platforms = get_connected_messaging_platforms()
-            messaging_actions = get_messaging_actions_for_platforms(connected_platforms)
-            conversation_mode_actions = base_actions + messaging_actions
+            from app.data.action.integrations._routing import get_messaging_actions_for_connected
+            conversation_mode_actions = base_actions + get_messaging_actions_for_connected()
         except Exception as e:
             logger.debug(f"[ACTION] Could not discover messaging actions: {e}")
             conversation_mode_actions = base_actions
@@ -124,12 +121,31 @@ async def select_action(
                     "output_schema": act.output_schema
                 })
 
+        # Pull just-in-time guidance for any integrations the user named.
+        # No-ops to "" when nothing matches; never raises. See the helper
+        # in the host app — kept out of agent_core so the package stays
+        # integration-agnostic.
+        try:
+            from app.data.action.integrations._integration_essentials import (
+                get_essentials_for_message,
+            )
+            # TODO: Is keyword based deterministic search good enough?
+            integration_essentials = get_essentials_for_message(query)
+            logger.info(
+                f"[ACTION] integration essentials: "
+                f"{len(integration_essentials)} chars injected"
+            )
+        except Exception as e:
+            logger.debug(f"[ACTION] integration essentials lookup failed: {e}")
+            integration_essentials = ""
+
         # Build the instruction prompt for the LLM
         full_prompt = SELECT_ACTION_PROMPT.format(
             event_stream=self.context_engine.get_event_stream(),
             memory_context=self.context_engine.get_memory_context(query),
             query=query,
             action_candidates=self._format_candidates(action_candidates),
+            integration_essentials=integration_essentials,
         )
 
         max_format_retries = 3
@@ -219,6 +235,31 @@ async def select_action_in_task(
         task_state = self.context_engine.get_task_state(session_id=session_id)
         memory_context = self.context_engine.get_memory_context(query, session_id=session_id)
         event_stream_content = self.context_engine.get_event_stream(session_id=session_id)
+
+        # Pull integration essentials the same way conversation-mode does
+        # (see select_action). Without this, the task-mode LLM loses sight
+        # of integration-specific shortcuts (e.g. WhatsApp's `to: "user"`
+        # self-send) once the agent enters task mode and starts asking the
+        # user for info the integration could look up itself.
+        # Match against both the current step's query and the task state so
+        # the platform name from the original user request still triggers a
+        # match even after the per-step query is generic ("Perform the next
+        # best action...").
+        try:
+            from app.data.action.integrations._integration_essentials import (
+                get_essentials_for_message,
+            )
+            integration_essentials = get_essentials_for_message(
+                f"{query}\n{task_state}"
+            )
+            logger.info(
+                f"[ACTION] task-mode integration essentials: "
+                f"{len(integration_essentials)} chars injected"
+            )
+        except Exception as e:
+            logger.debug(f"[ACTION] task-mode essentials lookup failed: {e}")
+            integration_essentials = ""
+
         static_prompt = SELECT_ACTION_IN_TASK_PROMPT.format(
             agent_state=self.context_engine.get_agent_state(session_id=session_id),
             task_state=task_state,
@@ -226,6 +267,7 @@ async def select_action_in_task(
             event_stream="",  # Empty for static prompt
             query=query,
             action_candidates=self._format_candidates(action_candidates),
+            integration_essentials=integration_essentials,
         )
         full_prompt = SELECT_ACTION_IN_TASK_PROMPT.format(
             agent_state=self.context_engine.get_agent_state(session_id=session_id),
@@ -234,6 +276,7 @@ async def select_action_in_task(
             event_stream=event_stream_content,
             query=query,
             action_candidates=self._format_candidates(action_candidates),
+            integration_essentials=integration_essentials,
         )
 
         max_format_retries = 3
@@ -325,6 +368,27 @@ async def select_action_in_simple_task(
         task_state = self.context_engine.get_task_state(session_id=session_id)
         memory_context = self.context_engine.get_memory_context(query, session_id=session_id)
         event_stream_content = self.context_engine.get_event_stream(session_id=session_id)
+
+        # Inject integration essentials so the simple-task LLM still sees
+        # integration-specific shortcuts (e.g. WhatsApp's `to: "user"`)
+        # even after the agent has left conversation mode. Match against
+        # the per-step query AND the task state so the original platform
+        # keyword still triggers a hit.
+        try:
+            from app.data.action.integrations._integration_essentials import (
+                get_essentials_for_message,
+            )
+            integration_essentials = get_essentials_for_message(
+                f"{query}\n{task_state}"
+            )
+            logger.info(
+                f"[ACTION] simple-task integration essentials: "
+                f"{len(integration_essentials)} chars injected"
+            )
+        except Exception as e:
+            logger.debug(f"[ACTION] simple-task essentials lookup failed: {e}")
+            integration_essentials = ""
+
         static_prompt = SELECT_ACTION_IN_SIMPLE_TASK_PROMPT.format(
             agent_state=self.context_engine.get_agent_state(session_id=session_id),
             task_state=task_state,
@@ -332,6 +396,7 @@ async def select_action_in_simple_task(
             event_stream="",  # Empty for static prompt
             query=query,
             action_candidates=self._format_candidates(action_candidates),
+            integration_essentials=integration_essentials,
         )
         full_prompt = SELECT_ACTION_IN_SIMPLE_TASK_PROMPT.format(
             agent_state=self.context_engine.get_agent_state(session_id=session_id),
@@ -340,6 +405,7 @@ async def select_action_in_simple_task(
             event_stream=event_stream_content,
             query=query,
             action_candidates=self._format_candidates(action_candidates),
+            integration_essentials=integration_essentials,
         )
 
         max_format_retries = 3
diff --git a/agent_core/core/impl/context/engine.py b/agent_core/core/impl/context/engine.py
index 05d89e74..781f017b 100644
--- a/agent_core/core/impl/context/engine.py
+++ b/agent_core/core/impl/context/engine.py
@@ -203,11 +203,14 @@ def create_system_environmental_context(self) -> str:
     def create_system_file_system_context(self) -> str:
         """Create a system message block with agent file system context."""
         try:
-            from app.config import AGENT_FILE_SYSTEM_PATH
+            from app.config import AGENT_FILE_SYSTEM_PATH, PROJECT_ROOT
+            skills_path = PROJECT_ROOT / "skills"
         except ImportError:
             AGENT_FILE_SYSTEM_PATH = "."
+            skills_path = "./skills"
         return AGENT_FILE_SYSTEM_CONTEXT_PROMPT.format(
             agent_file_system_path=AGENT_FILE_SYSTEM_PATH,
+            skills_path=skills_path,
         )
 
     def create_system_user_profile(self) -> str:
diff --git a/agent_core/core/impl/llm/errors.py b/agent_core/core/impl/llm/errors.py
index 052e2611..d0c303f2 100644
--- a/agent_core/core/impl/llm/errors.py
+++ b/agent_core/core/impl/llm/errors.py
@@ -2,180 +2,985 @@
 """
 LLM Error Classification Module.
 
-Provides user-friendly error messages for LLM-related failures.
-Uses proper exception types and HTTP status codes - no string pattern matching.
+Turns provider-specific exceptions into a structured `LLMErrorInfo` so the UI
+can render category-aware error cards (auth vs credits vs rate-limit vs
+server, etc.) instead of a single generic string.
+
+Provider error shapes were captured from live SDK responses — see comments
+on each per-provider extractor. The classifier is intentionally defensive
+(every body lookup tolerates `None` / wrong type) because some providers
+return string bodies, partial JSON, or undocumented fields.
+
+External callers:
+- `classify_llm_error(exc) -> LLMErrorInfo` is the new structured API.
+- `classify_llm_error_message(exc) -> str` is the back-compat shim for any
+  caller that only wants the plain string. Equivalent to
+  `classify_llm_error(exc).message`.
 """
 
 from __future__ import annotations
 
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
 
-from typing import Optional
 
-# Import provider exception types
+# Optional provider SDK imports — kept defensive so missing extras don't
+# break the classifier path.
 try:
     import openai
-except ImportError:
+except ImportError:  # pragma: no cover
     openai = None
 
 try:
     import anthropic
-except ImportError:
+except ImportError:  # pragma: no cover
     anthropic = None
 
+try:
+    import httpx
+except ImportError:  # pragma: no cover
+    httpx = None
+
 try:
     import requests
-except ImportError:
+except ImportError:  # pragma: no cover
     requests = None
 
 
-# User-friendly messages
-MSG_AUTH = "Unable to connect to AI service. Please check your API key in Settings."
+# ─── Public taxonomy ──────────────────────────────────────────────────
+
+
+class ErrorCategory(str, Enum):
+    AUTH = "auth"               # 401/403 — bad/missing key, key revoked
+    CREDIT = "credit"           # 402, "insufficient_quota", "credit_balance_too_low"
+    RATE_LIMIT = "rate_limit"   # 429 — transient
+    QUOTA = "quota"             # 429 + monthly/account scope (separable from per-min)
+    MODEL = "model"             # 404, "model_not_found"
+    BAD_REQUEST = "bad_request" # 400 — request malformed (context overflow, etc.)
+    BLOCKED = "blocked"         # safety filter (Gemini/Anthropic)
+    SERVER = "server"           # 5xx, "overloaded_error"
+    CONNECTION = "connection"   # network / timeout / DNS
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ErrorAction:
+    """A clickable affordance attached to an error.
+
+    `url` opens in a new tab; `action` is a frontend-resolved verb such as
+    "open_settings_model" — handled by the chat component, not by URL nav.
+    Exactly one of url/action should be set.
+    """
+    label: str
+    url: Optional[str] = None
+    action: Optional[str] = None
+
+
+@dataclass
+class LLMErrorInfo:
+    category: ErrorCategory
+    title: str                          # e.g. "Rate limited"
+    message: str                        # e.g. "Free-tier limit on Google AI Studio. Wait ~30s or add your own key."
+    provider: str                       # "openrouter", "anthropic", ...
+    upstream: Optional[str] = None      # "Google AI Studio" — present when OR proxies
+    model: Optional[str] = None
+    http_status: Optional[int] = None
+    retry_after_seconds: Optional[int] = None
+    actions: List[ErrorAction] = field(default_factory=list)
+    raw_message: Optional[str] = None   # truncated raw upstream text for "Show details"
+    request_id: Optional[str] = None    # for support tickets
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["category"] = self.category.value
+        return d
+
+
+# ─── Provider display names + category fallbacks ─────────────────────
+
+
+_PROVIDER_DISPLAY: Dict[str, str] = {
+    "openai": "OpenAI",
+    "openrouter": "OpenRouter",
+    "anthropic": "Anthropic",
+    "gemini": "Gemini",
+    "google": "Gemini",
+    "byteplus": "BytePlus",
+    "deepseek": "DeepSeek",
+    "grok": "Grok",
+    "moonshot": "Moonshot",
+    "minimax": "MiniMax",
+    "remote": "Ollama",
+}
+
+
+# Used only when the provider gave us no message at all (rare). Most
+# real-world errors have an upstream message that's already informative;
+# we lead with that and only append a short action hint.
+_FALLBACK_BODY_BY_CATEGORY: Dict[ErrorCategory, str] = {
+    ErrorCategory.AUTH:        "the API key was rejected",
+    ErrorCategory.CREDIT:      "out of credits",
+    ErrorCategory.RATE_LIMIT:  "rate-limited",
+    ErrorCategory.QUOTA:       "quota exceeded",
+    ErrorCategory.MODEL:       "the selected model is not available",
+    ErrorCategory.BAD_REQUEST: "the request was rejected",
+    ErrorCategory.BLOCKED:     "blocked by the provider's safety filter",
+    ErrorCategory.SERVER:      "the provider is unavailable",
+    ErrorCategory.CONNECTION:  "unable to reach the provider",
+    ErrorCategory.UNKNOWN:     "something went wrong",
+}
+
+
+# Back-compat string constants — some callers still import these directly.
+# Kept thin (single phrase) since the rich text now flows through info.message.
+MSG_AUTH = "The API key was rejected. Check your key in Settings."
+MSG_RATE_LIMIT = "The provider rate-limited this request. Try again shortly."
+MSG_MODEL = "The selected model is not available. Pick a different model in Settings."
+MSG_CONFIG = "The request was rejected by the provider."
+MSG_SERVICE = "The provider service is unavailable. Try again later."
+MSG_CONNECTION = "Could not reach the provider. Check your network connection."
+MSG_GENERIC = "Something went wrong calling the AI service."
 MSG_CONSECUTIVE_FAILURE = (
-    "LLM calls have failed {count} consecutive times. "
-    "Task aborted to prevent infinite retries. Please check your LLM configuration."
+    "Aborted after consecutive failures."
 )
 
 
+# ─── Consecutive-failure exception (preserves last classified info) ───
+
+
 class LLMConsecutiveFailureError(Exception):
     """Raised when LLM calls fail too many times consecutively.
 
-    This exception signals that the task should be aborted to prevent
-    infinite retry loops that flood logs and waste resources.
+    Carries the last classified `LLMErrorInfo` (when known) so the UI can
+    surface the *cause* of the failures, not just the count.
     """
 
-    def __init__(self, failure_count: int, last_error: Optional[Exception] = None):
+    def __init__(
+        self,
+        failure_count: int,
+        last_error: Optional[Exception] = None,
+        last_error_info: Optional[LLMErrorInfo] = None,
+    ):
         self.failure_count = failure_count
         self.last_error = last_error
+        self.last_error_info = last_error_info
         message = MSG_CONSECUTIVE_FAILURE.format(count=failure_count)
         if last_error:
             message += f" Last error: {last_error}"
         super().__init__(message)
-MSG_MODEL = "The selected AI model is not available. Please check your model settings."
-MSG_CONFIG = "AI service configuration error. The selected model may not support required features."
-MSG_RATE_LIMIT = "AI service is rate-limited. Please wait a moment and try again."
-MSG_SERVICE = "AI service is temporarily unavailable. Please try again later."
-MSG_CONNECTION = "Unable to reach AI service. Please check your internet connection."
-MSG_GENERIC = "An error occurred with the AI service. Please check your LLM configuration."
 
 
-def classify_llm_error(error: Exception) -> str:
-    """Classify an LLM error and return a user-friendly message.
+# ─── Public entry points ──────────────────────────────────────────────
 
-    Uses exception types and HTTP status codes for classification.
+
+def classify_llm_error(
+    error: Exception,
+    *,
+    provider: Optional[str] = None,
+    model: Optional[str] = None,
+) -> LLMErrorInfo:
+    """Classify an LLM error into structured info.
+
+    The user-visible string is `info.message` — fully self-contained, with
+    provider/upstream/raw/action hint composed inline. Other fields are
+    informational (logging, metrics) and not surfaced to the UI directly.
 
     Args:
-        error: The exception from the LLM call.
+        error: The exception raised by the provider call.
+        provider: Provider id (e.g. "openrouter", "anthropic"). Lets us
+            unwrap provider-specific error shapes (notably OpenRouter's
+            `metadata.provider_name`/`metadata.raw`).
+        model: Model id at call time. Stored on the info for logging.
 
     Returns:
-        A user-friendly error message.
+        `LLMErrorInfo` — never raises. For unrecognised shapes, falls back
+        to UNKNOWN with the raw exception text preserved as the message
+        (better than a generic stub — at least the user sees what blew up).
     """
-    # Check OpenAI exceptions
-    if openai is not None:
-        msg = _classify_openai_error(error)
-        if msg:
-            return msg
-
-    # Check Anthropic exceptions
-    if anthropic is not None:
-        msg = _classify_anthropic_error(error)
-        if msg:
-            return msg
-
-    # Check requests exceptions (BytePlus, remote/Ollama)
-    if requests is not None:
-        msg = _classify_requests_error(error)
-        if msg:
-            return msg
-
-    # Check for status_code attribute on any exception
-    status_code = _get_status_code(error)
-    if status_code:
-        return _message_from_status_code(status_code)
-
-    # Generic fallback
-    return MSG_GENERIC
-
-
-def _classify_openai_error(error: Exception) -> Optional[str]:
-    """Classify OpenAI SDK exceptions."""
-    if isinstance(error, openai.AuthenticationError):
-        return MSG_AUTH
-    if isinstance(error, openai.PermissionDeniedError):
-        return MSG_AUTH
-    if isinstance(error, openai.NotFoundError):
-        return MSG_MODEL
-    if isinstance(error, openai.BadRequestError):
-        return MSG_CONFIG
-    if isinstance(error, openai.RateLimitError):
-        return MSG_RATE_LIMIT
-    if isinstance(error, openai.InternalServerError):
-        return MSG_SERVICE
-    if isinstance(error, openai.APIConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, openai.APITimeoutError):
-        return MSG_CONNECTION
-    if isinstance(error, openai.APIStatusError):
-        return _message_from_status_code(error.status_code)
-    return None
+    info = _try_classify(error, provider=provider)
+    if info is None:
+        # Don't fabricate a generic message — the raw exception text is
+        # almost always more informative than any stub we could write.
+        raw = _truncate(str(error)) or "AI service error"
+        info = LLMErrorInfo(
+            category=ErrorCategory.UNKNOWN,
+            title="AI service error",
+            message=raw,
+            provider=provider or "unknown",
+            raw_message=raw,
+        )
+
+    if model and info.model is None:
+        info.model = model
+
+    return info
+
+
+def classify_llm_error_message(error: Exception) -> str:
+    """Back-compat shim — returns just the user-facing string.
+
+    Equivalent to `classify_llm_error(error).message`. Kept so existing
+    call sites that only need a string don't have to refactor in this PR.
+    """
+    return classify_llm_error(error).message
 
 
-def _classify_anthropic_error(error: Exception) -> Optional[str]:
-    """Classify Anthropic SDK exceptions."""
-    if isinstance(error, anthropic.AuthenticationError):
-        return MSG_AUTH
-    if isinstance(error, anthropic.PermissionDeniedError):
-        return MSG_AUTH
-    if isinstance(error, anthropic.NotFoundError):
-        return MSG_MODEL
-    if isinstance(error, anthropic.BadRequestError):
-        return MSG_CONFIG
-    if isinstance(error, anthropic.RateLimitError):
-        return MSG_RATE_LIMIT
-    if isinstance(error, anthropic.InternalServerError):
-        return MSG_SERVICE
-    if isinstance(error, anthropic.APIConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, anthropic.APITimeoutError):
-        return MSG_CONNECTION
-    if isinstance(error, anthropic.APIStatusError):
-        return _message_from_status_code(error.status_code)
-    return None
+# ─── Dispatcher ───────────────────────────────────────────────────────
+
+
+def _try_classify(
+    error: Exception,
+    *,
+    provider: Optional[str],
+) -> Optional[LLMErrorInfo]:
+    """Try each provider extractor in turn. Returns None if nothing matches."""
+    # OpenAI SDK exceptions cover openai/openrouter/grok/deepseek/moonshot/minimax
+    if openai is not None and isinstance(error, openai.OpenAIError):
+        return _classify_openai_compat(error, provider or "openai")
+
+    # Anthropic SDK exceptions
+    if anthropic is not None and isinstance(error, anthropic.AnthropicError):
+        return _classify_anthropic(error, provider or "anthropic")
+
+    # httpx errors are how the Gemini and BytePlus paths surface failures
+    if httpx is not None and isinstance(error, httpx.HTTPStatusError):
+        return _classify_httpx_status(error, provider)
+    if httpx is not None and isinstance(error, httpx.RequestError):
+        return _classify_httpx_connection(error, provider)
+
+    # `requests` library — older code paths still raise these
+    if requests is not None and isinstance(error, requests.exceptions.RequestException):
+        return _classify_requests(error, provider)
 
+    # Gemini's custom error type (raised by our REST client)
+    msg = str(error)
+    if "Gemini" in msg or "promptFeedback" in msg or "blocked" in msg.lower():
+        return _classify_gemini_runtime(error, provider or "gemini")
 
-def _classify_requests_error(error: Exception) -> Optional[str]:
-    """Classify requests library exceptions (for BytePlus/Ollama)."""
-    if isinstance(error, requests.exceptions.HTTPError):
-        if error.response is not None:
-            return _message_from_status_code(error.response.status_code)
-        return MSG_SERVICE
-    if isinstance(error, requests.exceptions.ConnectionError):
-        return MSG_CONNECTION
-    if isinstance(error, requests.exceptions.Timeout):
-        return MSG_CONNECTION
     return None
 
 
-def _get_status_code(error: Exception) -> Optional[int]:
-    """Extract HTTP status code from exception if available."""
-    # Check for status_code attribute
-    if hasattr(error, "status_code"):
-        return getattr(error, "status_code", None)
-    # Check for response.status_code (requests-style)
-    if hasattr(error, "response") and hasattr(error.response, "status_code"):
-        return error.response.status_code
+# ─── OpenAI / OpenAI-compatible (openai, openrouter, grok, deepseek, ...) ───
+
+
+def _classify_openai_compat(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Handle openai SDK exception hierarchy.
+
+    Real shapes captured from live probes:
+    - OpenAI 401:    body.code = "invalid_api_key" (string), body.type = "invalid_request_error"
+    - OpenRouter 401: body = {"message": "User not found.", "code": 401}  ← flat, code is INT
+    - OpenRouter 429: body = {"message": ..., "code": 429,
+                              "metadata": {"raw": ..., "provider_name": "...", "is_byok": false}}
+    - Grok 400 (auth!): body is a STRING, status is 400 (NOT 401)
+    - DeepSeek 401:  body.type = "authentication_error", body.code = "invalid_request_error"
+    """
+    body = getattr(exc, "body", None)
+    status = getattr(exc, "status_code", None)
+    request_id = getattr(exc, "request_id", None)
+
+    body_dict: Dict[str, Any] = {}
+    if isinstance(body, dict):
+        body_dict = body
+    elif isinstance(body, str):
+        # Grok edge case — body is the raw string message
+        body_dict = {"message": body}
+
+    # Pick the cleanest user-facing string out of the body. Different
+    # OpenAI-compatible providers stash it under different keys:
+    #   - OpenAI / OpenRouter / DeepSeek: body["message"]
+    #   - Grok bad-model (400):           body["error"]   (a string)
+    #   - Grok bad-key (400, body=string):  handled above by string→dict shim
+    # Falling back to str(exc) produces "Error code: 400 - {full body dict}",
+    # which is too noisy for the chat — only use it when nothing else fits.
+    raw_message_candidate: Optional[str] = None
+    for key in ("message", "error"):
+        v = body_dict.get(key)
+        if isinstance(v, str) and v:
+            raw_message_candidate = v
+            break
+    raw_message: str = raw_message_candidate or str(exc)
+    code = body_dict.get("code")
+    error_type = body_dict.get("type")
+
+    upstream: Optional[str] = None
+    metadata = body_dict.get("metadata") if isinstance(body_dict.get("metadata"), dict) else None
+
+    # OpenRouter wraps upstream errors. The upstream's verbatim message is
+    # FAR more useful than OR's "Provider returned error" wrapper.
+    if provider == "openrouter" and metadata:
+        if isinstance(metadata.get("provider_name"), str):
+            upstream = metadata["provider_name"]
+        if isinstance(metadata.get("raw"), str) and metadata["raw"]:
+            raw_message = metadata["raw"]
+
+    # ── Category resolution ────────────────────────────────────────
+    category = _category_from_openai_exc(exc, status=status, body_dict=body_dict, raw=raw_message)
+
+    # OpenAI string codes are the gold standard signal where present
+    if isinstance(code, str):
+        if code == "insufficient_quota":
+            category = ErrorCategory.CREDIT
+        elif code == "rate_limit_exceeded":
+            category = ErrorCategory.RATE_LIMIT
+        elif code == "context_length_exceeded":
+            category = ErrorCategory.BAD_REQUEST
+        elif code in ("model_not_found", "invalid_model"):
+            category = ErrorCategory.MODEL
+        elif code == "invalid_api_key":
+            category = ErrorCategory.AUTH
+        # Chinese provider credit codes (DeepSeek, MiniMax, Moonshot, Qwen)
+        elif code in ("insufficient_user_quota", "quota_exceeded", "balance_insufficient",
+                      "BillingException", "InsufficientQuota"):
+            category = ErrorCategory.CREDIT
+        # Chinese provider content-filter codes
+        elif code in ("content_policy_violation", "content_filter", "output_moderation",
+                      "ContentAuditException", "DataInspectionFailed"):
+            category = ErrorCategory.BLOCKED
+
+    # Anthropic-style nested error type can appear when OR proxies Anthropic
+    if isinstance(error_type, str):
+        if error_type == "credit_balance_too_low":
+            category = ErrorCategory.CREDIT
+        elif error_type == "overloaded_error":
+            category = ErrorCategory.SERVER
+        # OpenRouter content moderation (OR itself flags the content before forwarding)
+        elif error_type == "moderation":
+            category = ErrorCategory.BLOCKED
+
+    # OpenRouter uses 402 for empty wallet; the openai SDK doesn't have a
+    # dedicated 402 exception so we land in APIStatusError — adjust here.
+    if status == 402:
+        category = ErrorCategory.CREDIT
+
+    # OpenRouter 403 can mean content moderation, not just auth — check body
+    if status == 403 and provider == "openrouter":
+        raw_lower = raw_message.lower()
+        if any(k in raw_lower for k in ("moderat", "blocked", "policy", "content", "flagged")):
+            category = ErrorCategory.BLOCKED
+
+    # Localised error message detection — Chinese, Japanese, Korean providers
+    # (DeepSeek, Moonshot, MiniMax, Qwen, rinna, CLOVA, etc.) may return
+    # error text in their native language when routed via OpenRouter.
+    category = _refine_category_from_localised(raw_message, category)
+
+    # ── Retry-After ────────────────────────────────────────────────
+    retry_after = _retry_after_seconds(exc)
+
+    # ── User-facing message ────────────────────────────────────────
+    message = _compose_message(category, raw_message, provider, upstream, retry_after_seconds=retry_after)
+    actions = _default_actions(category, provider, upstream, metadata)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category, upstream=upstream),
+        message=message,
+        provider=provider,
+        upstream=upstream,
+        http_status=status if isinstance(status, int) else None,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+        request_id=request_id if isinstance(request_id, str) else None,
+    )
+
+
+def _category_from_openai_exc(
+    exc: Exception,
+    *,
+    status: Optional[int],
+    body_dict: Dict[str, Any],
+    raw: str,
+) -> ErrorCategory:
+    """Map openai SDK exception type → category. Defensive for missing SDK."""
+    if openai is None:  # pragma: no cover
+        return _category_from_status(status)
+
+    if isinstance(exc, openai.AuthenticationError):
+        return ErrorCategory.AUTH
+    if isinstance(exc, openai.PermissionDeniedError):
+        # Often "billing-blocked" or "country-not-supported" — surface as AUTH-ish.
+        return ErrorCategory.AUTH
+    if isinstance(exc, openai.NotFoundError):
+        return ErrorCategory.MODEL
+    if isinstance(exc, openai.RateLimitError):
+        return ErrorCategory.RATE_LIMIT
+    if isinstance(exc, openai.BadRequestError):
+        # Grok returns 400 for auth — sniff body
+        lower = raw.lower()
+        if "api key" in lower or "api_key" in lower or "invalid_api_key" in lower:
+            return ErrorCategory.AUTH
+        if "context" in lower and ("length" in lower or "too long" in lower or "exceeds" in lower):
+            return ErrorCategory.BAD_REQUEST
+        if "model" in lower and ("not found" in lower or "not available" in lower or "does not exist" in lower):
+            return ErrorCategory.MODEL
+        if "blocked" in lower or "safety" in lower or "policy" in lower:
+            return ErrorCategory.BLOCKED
+        return ErrorCategory.BAD_REQUEST
+    if isinstance(exc, openai.InternalServerError):
+        return ErrorCategory.SERVER
+    if isinstance(exc, (openai.APIConnectionError, openai.APITimeoutError)):
+        return ErrorCategory.CONNECTION
+    if isinstance(exc, openai.APIStatusError):
+        return _category_from_status(status)
+
+    return _category_from_status(status)
+
+
+# ─── Anthropic ────────────────────────────────────────────────────────
+
+
+def _classify_anthropic(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Anthropic SDK shape:
+        body = {
+          "type": "error",
+          "error": {"type": "authentication_error" | ..., "message": "..."},
+          "request_id": "..."
+        }
+    """
+    if anthropic is None:  # pragma: no cover
+        return _fallback_unknown(exc, provider)
+
+    body = getattr(exc, "body", None)
+    status = getattr(exc, "status_code", None)
+    request_id = getattr(exc, "request_id", None)
+
+    error_block = {}
+    if isinstance(body, dict):
+        if isinstance(body.get("error"), dict):
+            error_block = body["error"]
+        elif isinstance(body.get("type"), str):
+            error_block = body
+
+    a_type = error_block.get("type") if isinstance(error_block, dict) else None
+    raw_message = (
+        error_block.get("message")
+        if isinstance(error_block, dict) and isinstance(error_block.get("message"), str)
+        else str(exc)
+    )
+
+    # Map Anthropic's typed error names. These are richer than HTTP codes.
+    type_to_category = {
+        "authentication_error": ErrorCategory.AUTH,
+        "permission_error": ErrorCategory.AUTH,
+        "credit_balance_too_low": ErrorCategory.CREDIT,
+        "billing_error": ErrorCategory.CREDIT,
+        "rate_limit_error": ErrorCategory.RATE_LIMIT,
+        "overloaded_error": ErrorCategory.SERVER,
+        "api_error": ErrorCategory.SERVER,
+        "invalid_request_error": ErrorCategory.BAD_REQUEST,
+        "not_found_error": ErrorCategory.MODEL,
+    }
+
+    category: Optional[ErrorCategory] = None
+    if isinstance(a_type, str) and a_type in type_to_category:
+        category = type_to_category[a_type]
+    else:
+        # Fall back to SDK exception class
+        if isinstance(exc, anthropic.AuthenticationError):
+            category = ErrorCategory.AUTH
+        elif isinstance(exc, anthropic.PermissionDeniedError):
+            category = ErrorCategory.AUTH
+        elif isinstance(exc, anthropic.NotFoundError):
+            category = ErrorCategory.MODEL
+        elif isinstance(exc, anthropic.RateLimitError):
+            category = ErrorCategory.RATE_LIMIT
+        elif isinstance(exc, anthropic.InternalServerError):
+            category = ErrorCategory.SERVER
+        elif isinstance(exc, (anthropic.APIConnectionError, anthropic.APITimeoutError)):
+            category = ErrorCategory.CONNECTION
+        elif isinstance(exc, anthropic.BadRequestError):
+            lower = raw_message.lower()
+            if "prompt is too long" in lower or "maximum context length" in lower:
+                category = ErrorCategory.BAD_REQUEST
+            else:
+                category = ErrorCategory.BAD_REQUEST
+        else:
+            category = _category_from_status(status)
+
+    retry_after = _retry_after_seconds(exc)
+
+    actions = _default_actions(category, provider, upstream=None, metadata=None)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw_message, provider, upstream=None, retry_after_seconds=retry_after),
+        provider=provider,
+        upstream=None,
+        http_status=status if isinstance(status, int) else None,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+        request_id=request_id if isinstance(request_id, str) else None,
+    )
+
+
+# ─── Gemini ────────────────────────────────────────────────────────────
+
+
+def _classify_httpx_status(exc: Exception, provider: Optional[str]) -> LLMErrorInfo:
+    """httpx.HTTPStatusError — covers Gemini and BytePlus paths.
+
+    Gemini body: {"error":{"code":400,"message":"...","status":"INVALID_ARGUMENT",
+                  "details":[{"reason":"API_KEY_INVALID",...}]}}
+    BytePlus body: {"error":{"code":"AuthenticationError","message":"..."}}
+    """
+    if httpx is None:  # pragma: no cover
+        return _fallback_unknown(exc, provider or "unknown")
+
+    response = getattr(exc, "response", None)
+    status = response.status_code if response is not None else None
+    text = response.text if response is not None else ""
+    body_dict = _safe_json(text)
+
+    err = body_dict.get("error") if isinstance(body_dict.get("error"), dict) else {}
+    raw_message = err.get("message") if isinstance(err.get("message"), str) else str(exc)
+
+    # Detect Gemini specifically by reason field
+    reason: Optional[str] = None
+    details = err.get("details") if isinstance(err.get("details"), list) else []
+    for d in details:
+        if isinstance(d, dict) and isinstance(d.get("reason"), str):
+            reason = d["reason"]
+            break
+
+    inferred_provider = provider or ("gemini" if reason or "generativelanguage" in text else "unknown")
+
+    # Gemini's REST API returns 400 for invalid keys — map by reason field
+    if reason == "API_KEY_INVALID":
+        category = ErrorCategory.AUTH
+    elif reason == "RESOURCE_EXHAUSTED":
+        category = ErrorCategory.RATE_LIMIT
+    elif reason == "PERMISSION_DENIED":
+        category = ErrorCategory.AUTH
+    else:
+        category = _category_from_status(status)
+        # BytePlus encodes auth errors via err.code = "AuthenticationError"
+        if isinstance(err.get("code"), str) and "auth" in err["code"].lower():
+            category = ErrorCategory.AUTH
+
+    retry_after = None
+    if response is not None:
+        ra = response.headers.get("retry-after")
+        if ra is not None:
+            try:
+                retry_after = int(float(ra))
+            except (ValueError, TypeError):
+                retry_after = None
+
+    actions = _default_actions(category, inferred_provider, upstream=None, metadata=None)
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw_message, inferred_provider, upstream=None),
+        provider=inferred_provider,
+        upstream=None,
+        http_status=status,
+        retry_after_seconds=retry_after,
+        actions=actions,
+        raw_message=_truncate(raw_message),
+    )
+
+
+def _classify_httpx_connection(exc: Exception, provider: Optional[str]) -> LLMErrorInfo:
+    raw = _truncate(str(exc))
+    return LLMErrorInfo(
+        category=ErrorCategory.CONNECTION,
+        title=_title_for(ErrorCategory.CONNECTION),
+        message=_compose_message(ErrorCategory.CONNECTION, raw, provider or "unknown", upstream=None),
+        provider=provider or "unknown",
+        raw_message=raw,
+    )
+
+
+def _classify_gemini_runtime(exc: Exception, provider: str) -> LLMErrorInfo:
+    """Gemini's GeminiAPIError — raised when the response shape signals an issue
+    that isn't an HTTP failure (e.g. promptFeedback.blockReason)."""
+    raw = str(exc)
+    lower = raw.lower()
+
+    if "blocked" in lower or "promptfeedback" in lower or "safety" in lower:
+        category = ErrorCategory.BLOCKED
+    else:
+        category = ErrorCategory.UNKNOWN
+
+    return LLMErrorInfo(
+        category=category,
+        title=_title_for(category),
+        message=_compose_message(category, raw, provider, upstream=None),
+        provider=provider,
+        raw_message=_truncate(raw),
+        actions=_default_actions(category, provider, upstream=None, metadata=None),
+    )
+
+
+# ─── requests library (legacy callers) ────────────────────────────────
+
+
+def _classify_requests(exc: Exception, provider: Optional[str]) -> Optional[LLMErrorInfo]:
+    if requests is None:  # pragma: no cover
+        return None
+    if isinstance(exc, requests.exceptions.HTTPError):
+        response = exc.response
+        if response is not None:
+            status = response.status_code
+            try:
+                body = response.json()
+            except Exception:
+                body = {}
+            err = body.get("error") if isinstance(body.get("error"), dict) else {}
+            raw_message = err.get("message") if isinstance(err.get("message"), str) else response.text
+            return LLMErrorInfo(
+                category=_category_from_status(status),
+                title=_title_for(_category_from_status(status)),
+                message=_compose_message(_category_from_status(status), raw_message, provider or "unknown", upstream=None),
+                provider=provider or "unknown",
+                http_status=status,
+                raw_message=_truncate(raw_message),
+            )
+    if isinstance(exc, (requests.exceptions.ConnectionError, requests.exceptions.Timeout)):
+        raw = _truncate(str(exc))
+        return LLMErrorInfo(
+            category=ErrorCategory.CONNECTION,
+            title=_title_for(ErrorCategory.CONNECTION),
+            message=_compose_message(ErrorCategory.CONNECTION, raw, provider or "unknown", upstream=None),
+            provider=provider or "unknown",
+            raw_message=raw,
+        )
     return None
 
 
-def _message_from_status_code(status_code: int) -> str:
-    """Map HTTP status code to user-friendly message."""
-    if status_code == 401 or status_code == 403:
-        return MSG_AUTH
-    if status_code == 404:
-        return MSG_MODEL
-    if status_code == 400:
-        return MSG_CONFIG
-    if status_code == 429:
-        return MSG_RATE_LIMIT
-    if 500 <= status_code < 600:
-        return MSG_SERVICE
-    return MSG_GENERIC
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+
+def _category_from_status(status: Optional[int]) -> ErrorCategory:
+    if status is None:
+        return ErrorCategory.UNKNOWN
+    if status in (401, 403):
+        return ErrorCategory.AUTH
+    if status == 402:
+        return ErrorCategory.CREDIT
+    if status == 404:
+        return ErrorCategory.MODEL
+    if status == 400:
+        return ErrorCategory.BAD_REQUEST
+    if status == 408:
+        return ErrorCategory.CONNECTION  # request timeout
+    if status == 429:
+        return ErrorCategory.RATE_LIMIT
+    if status == 524:
+        return ErrorCategory.SERVER  # Cloudflare upstream timeout (common on OpenRouter)
+    if 500 <= status < 600:
+        return ErrorCategory.SERVER
+    return ErrorCategory.UNKNOWN
+
+
+def _retry_after_seconds(exc: Exception) -> Optional[int]:
+    response = getattr(exc, "response", None)
+    if response is None:
+        return None
+    ra = None
+    try:
+        ra = response.headers.get("retry-after")
+    except AttributeError:
+        return None
+    if not ra:
+        return None
+    try:
+        return int(float(ra))
+    except (ValueError, TypeError):
+        return None
+
+
+_CATEGORY_TITLES: Dict[ErrorCategory, str] = {
+    ErrorCategory.AUTH: "Invalid API key",
+    ErrorCategory.CREDIT: "Out of credits",
+    ErrorCategory.RATE_LIMIT: "Rate limited",
+    ErrorCategory.QUOTA: "Quota exceeded",
+    ErrorCategory.MODEL: "Incorrect model id",
+    ErrorCategory.BAD_REQUEST: "Bad request",
+    ErrorCategory.BLOCKED: "Blocked by safety filter",
+    ErrorCategory.SERVER: "Provider service unavailable",
+    ErrorCategory.CONNECTION: "Cannot reach provider",
+    ErrorCategory.UNKNOWN: "AI service error",
+}
+
+
+# Categories where we suppress the leading title sentence — the raw
+# provider message is already self-explanatory or the title would just
+# repeat the upstream's words.
+_SKIP_TITLE_CATEGORIES = {ErrorCategory.UNKNOWN, ErrorCategory.BAD_REQUEST}
+
+
+def _title_for(category: ErrorCategory, *, upstream: Optional[str] = None) -> str:
+    """Short title — used for logging/metrics and for the leading sentence
+    of the user-facing chat message (see `_compose_message`)."""
+    base = _CATEGORY_TITLES.get(category, "AI service error")
+    if upstream and category in (ErrorCategory.RATE_LIMIT, ErrorCategory.SERVER, ErrorCategory.BLOCKED):
+        return f"{base} ({upstream})"
+    return base
+
+
+def _compose_message(
+    category: ErrorCategory,
+    raw_message: str,
+    provider: str,
+    upstream: Optional[str],
+    *,
+    retry_after_seconds: Optional[int] = None,
+) -> str:
+    """Build the single user-facing string shown in the chat error bubble.
+
+    Format:  "<Category title>. <Provider> [via <Upstream>]: <raw>. <action hint>."
+
+    The category title leads so users instantly know *what kind* of error
+    happened — important when the provider's raw text is terse (Anthropic
+    returns just `"model: claude-sonnet-4-5-2025092945"` for a bad model
+    id, which is meaningless without context). The raw provider text
+    follows so users see the exact upstream message. The action hint
+    closes when it adds value beyond what the raw already says.
+    """
+    raw = (raw_message or "").strip()
+    if raw.lower() == "none":
+        raw = ""
+    raw = _truncate(raw.rstrip("."), limit=400)
+    if not raw:
+        raw = _FALLBACK_BODY_BY_CATEGORY.get(category, "an error occurred")
+
+    # Lead with category title (e.g. "Incorrect model id.") unless the
+    # category is too vague to title meaningfully.
+    if category in _SKIP_TITLE_CATEGORIES:
+        lead = ""
+    else:
+        lead = f"{_title_for(category, upstream=upstream)}."
+
+    name = _PROVIDER_DISPLAY.get(provider, "")
+    if name:
+        prefix = f"{name} (via {upstream})" if upstream else name
+        provider_part = f"{prefix}: {raw}"
+    else:
+        provider_part = raw
+
+    body = f"{lead} {provider_part}" if lead else provider_part
+    return _append_hint(body, category, provider, retry_after_seconds, raw.lower())
+
+
+def _append_hint(
+    body: str,
+    category: ErrorCategory,
+    provider: str,
+    retry_after: Optional[int],
+    raw_lower: str,
+) -> str:
+    """Append a short action hint, suppressed when the provider's own raw
+    text already covers it (avoids "...add your own key. Try again shortly.")."""
+    base = body.rstrip(".")
+
+    if category == ErrorCategory.AUTH:
+        if "key" in raw_lower or "settings" in raw_lower:
+            return f"{base}."
+        return f"{base}. Check your API key in Settings."
+
+    if category == ErrorCategory.CREDIT:
+        if any(s in raw_lower for s in ("billing", "credit", "top up", "topup")):
+            return f"{base}."
+        if provider == "openrouter":
+            return f"{base}. Top up at https://openrouter.ai/credits."
+        if provider == "openai":
+            return f"{base}. Manage billing at https://platform.openai.com/account/billing."
+        if provider == "anthropic":
+            return f"{base}. Manage billing at https://console.anthropic.com/settings/billing."
+        return f"{base}."
+
+    if category == ErrorCategory.RATE_LIMIT:
+        if retry_after:
+            return f"{base}. Try again in {retry_after}s."
+        if any(s in raw_lower for s in (
+            "byok", "your own key", "openrouter.ai/settings", "retry", "wait", "try again",
+        )):
+            return f"{base}."
+        return f"{base}. Try again shortly."
+
+    if category == ErrorCategory.QUOTA:
+        if "billing" in raw_lower or "usage" in raw_lower:
+            return f"{base}."
+        if provider == "openai":
+            return f"{base}. Manage usage at https://platform.openai.com/usage."
+        return f"{base}."
+
+    if category == ErrorCategory.MODEL:
+        if "settings" in raw_lower:
+            return f"{base}."
+        return f"{base}. Use a correct model in Settings."
+
+    if category == ErrorCategory.BLOCKED:
+        return f"{base}. Edit your prompt and retry."
+
+    if category == ErrorCategory.SERVER:
+        if "try again" in raw_lower or "retry" in raw_lower:
+            return f"{base}."
+        return f"{base}. Try again later."
+
+    if category == ErrorCategory.CONNECTION:
+        if provider == "remote":
+            return f"{base}. Check that Ollama is running."
+        if "network" in raw_lower or "connection" in raw_lower:
+            return f"{base}."
+        return f"{base}. Check your network connection."
+
+    # BAD_REQUEST / UNKNOWN — raw is the most informative thing we can show
+    return f"{base}."
+
+
+def _default_actions(
+    category: ErrorCategory,
+    provider: str,
+    upstream: Optional[str],
+    metadata: Optional[Dict[str, Any]],
+) -> List[ErrorAction]:
+    """Per-(category, provider) action affordances.
+
+    Keep this list short — each action is a click target the user is more
+    likely to actually want than just dismissing the error.
+    """
+    actions: List[ErrorAction] = []
+
+    if category == ErrorCategory.CREDIT:
+        if provider == "openrouter":
+            actions.append(ErrorAction(label="Top up credits", url="https://openrouter.ai/credits"))
+        elif provider == "openai":
+            actions.append(ErrorAction(label="Manage billing", url="https://platform.openai.com/account/billing"))
+        elif provider == "anthropic":
+            actions.append(ErrorAction(label="Manage billing", url="https://console.anthropic.com/settings/billing"))
+        actions.append(ErrorAction(label="Open settings", action="open_settings_model"))
+
+    elif category == ErrorCategory.RATE_LIMIT:
+        if provider == "openrouter" and metadata and metadata.get("is_byok") is False:
+            # Free-tier user — point at OR integrations page for BYOK
+            actions.append(ErrorAction(label="Add your own key", url="https://openrouter.ai/settings/integrations"))
+        actions.append(ErrorAction(label="Open settings", action="open_settings_model"))
+
+    elif category == ErrorCategory.QUOTA:
+        if provider == "openai":
+            actions.append(ErrorAction(label="Manage usage", url="https://platform.openai.com/usage"))
+
+    return actions
+
+
+def _has_action(info: LLMErrorInfo, action_value: str) -> bool:
+    return any(a.action == action_value for a in info.actions)
+
+
+def _refine_category_from_localised(raw_message: str, current: ErrorCategory) -> ErrorCategory:
+    """Detect category from non-English error text returned by Asian providers.
+
+    Covers Chinese (DeepSeek, MiniMax, Moonshot, Qwen, Baidu ERNIE),
+    Japanese (rinna, Sakura, ELYZA), and Korean (CLOVA, HyperCLOVA) providers
+    that may return error messages in their native language when routed via
+    OpenRouter or called directly.
+
+    Only overrides UNKNOWN / BAD_REQUEST — specific categories already resolved
+    from HTTP status or error codes take priority.
+
+    Handles arbitrary UTF-8 safely: Python str containment checks on Unicode
+    strings are always safe regardless of script or encoding.
+    """
+    if not raw_message or current not in (ErrorCategory.UNKNOWN, ErrorCategory.BAD_REQUEST):
+        return current
+
+    # Normalise: ensure we have a plain str (guards against bytes leaking in)
+    try:
+        msg = raw_message if isinstance(raw_message, str) else raw_message.decode("utf-8", errors="replace")
+    except Exception:
+        return current
+
+    # ── Chinese ───────────────────────────────────────────────────────
+    _ZH_BLOCKED = ("违禁", "违规", "内容政策", "不合规", "审核不通过", "违反规定",
+                   "敏感内容", "内容安全", "内容审核", "政治敏感", "黄色信息")
+    _ZH_CREDIT  = ("余额不足", "额度不足", "账户欠费", "账户余额", "充值", "欠费",
+                   "配额不足", "余额不够")
+    _ZH_AUTH    = ("无效的API", "鉴权失败", "认证失败", "密钥无效", "API密钥",
+                   "身份验证", "未授权")
+    _ZH_RATE    = ("频率限制", "请求过多", "限流", "速率限制", "调用频率",
+                   "访问频率", "接口限流")
+    _ZH_CONTEXT = ("超出最大长度", "上下文长度", "tokens超出", "输入过长",
+                   "超过最大token")
+
+    # ── Japanese ──────────────────────────────────────────────────────
+    _JA_BLOCKED = ("禁止されたコンテンツ", "コンテンツポリシー", "不適切なコンテンツ",
+                   "ポリシー違反", "有害なコンテンツ", "安全フィルター")
+    _JA_CREDIT  = ("残高不足", "クレジット不足", "料金超過", "利用上限", "残高が不足",
+                   "クォータ超過")
+    _JA_AUTH    = ("認証エラー", "認証に失敗", "APIキーが無効", "無効なAPIキー",
+                   "認証情報", "アクセス拒否")
+    _JA_RATE    = ("レート制限", "リクエスト制限", "利用制限", "リクエストが多すぎ",
+                   "スロットリング")
+    _JA_CONTEXT = ("トークン数が上限", "コンテキスト長", "入力が長すぎ", "最大トークン",
+                   "トークン超過")
+
+    # ── Korean ────────────────────────────────────────────────────────
+    _KO_BLOCKED = ("콘텐츠 정책 위반", "부적절한 콘텐츠", "금지된 콘텐츠",
+                   "안전 필터", "정책 위반")
+    _KO_CREDIT  = ("잔액 부족", "크레딧 부족", "한도 초과", "요금 미납", "충전 필요")
+    _KO_AUTH    = ("인증 실패", "잘못된 API 키", "유효하지 않은 키", "인증 오류",
+                   "액세스 거부")
+    _KO_RATE    = ("속도 제한", "요청 제한", "너무 많은 요청", "처리율 제한")
+    _KO_CONTEXT = ("토큰 초과", "컨텍스트 길이 초과", "입력이 너무 깁니다",
+                   "최대 토큰")
+
+    _BLOCKED_KWS = _ZH_BLOCKED + _JA_BLOCKED + _KO_BLOCKED
+    _CREDIT_KWS  = _ZH_CREDIT  + _JA_CREDIT  + _KO_CREDIT
+    _AUTH_KWS    = _ZH_AUTH    + _JA_AUTH    + _KO_AUTH
+    _RATE_KWS    = _ZH_RATE    + _JA_RATE    + _KO_RATE
+    _CONTEXT_KWS = _ZH_CONTEXT + _JA_CONTEXT + _KO_CONTEXT
+
+    for kw in _BLOCKED_KWS:
+        if kw in msg:
+            return ErrorCategory.BLOCKED
+    for kw in _CREDIT_KWS:
+        if kw in msg:
+            return ErrorCategory.CREDIT
+    for kw in _AUTH_KWS:
+        if kw in msg:
+            return ErrorCategory.AUTH
+    for kw in _RATE_KWS:
+        if kw in msg:
+            return ErrorCategory.RATE_LIMIT
+    for kw in _CONTEXT_KWS:
+        if kw in msg:
+            return ErrorCategory.BAD_REQUEST
+
+    return current
+
+
+def _safe_json(text: str) -> Dict[str, Any]:
+    if not text:
+        return {}
+    try:
+        import json
+        result = json.loads(text)
+        return result if isinstance(result, dict) else {}
+    except Exception:
+        return {}
+
+
+def _truncate(s: Optional[str], limit: int = 500) -> str:
+    if s is None:
+        return ""
+    s = str(s)
+    if len(s) <= limit:
+        return s
+    return s[:limit].rstrip() + "…"
+
+
+def _fallback_unknown(exc: Exception, provider: str) -> LLMErrorInfo:
+    raw = _truncate(str(exc)) or "AI service error"
+    return LLMErrorInfo(
+        category=ErrorCategory.UNKNOWN,
+        title="AI service error",
+        message=raw,
+        provider=provider,
+        raw_message=raw,
+    )
\ No newline at end of file
diff --git a/agent_core/core/impl/llm/interface.py b/agent_core/core/impl/llm/interface.py
index 913453ca..3fdd61a7 100644
--- a/agent_core/core/impl/llm/interface.py
+++ b/agent_core/core/impl/llm/interface.py
@@ -29,7 +29,7 @@
     get_cache_config,
     get_cache_metrics,
 )
-from agent_core.core.impl.llm.errors import LLMConsecutiveFailureError
+from agent_core.core.impl.llm.errors import LLMConsecutiveFailureError, classify_llm_error
 from agent_core.core.hooks import (
     GetTokenCountHook,
     SetTokenCountHook,
@@ -42,6 +42,15 @@
 from agent_core.utils.logger import logger
 
 
+class _EmptyResponse(Exception):
+    """Raised when a provider returns empty/error content and the failure has already been counted.
+
+    Using a distinct class prevents the outer except-Exception block in
+    _generate_response_sync from double-incrementing the consecutive-failure
+    counter for the same call.
+    """
+
+
 # Models that do NOT support assistant message prefill
 # These require output_config.format for structured JSON output
 _ANTHROPIC_NO_PREFILL_PATTERNS = (
@@ -367,7 +376,7 @@ def _generate_response_sync(
             logger.info(f"[LLM SEND] system={system_prompt} | user={user_prompt}")
 
         try:
-            if self.provider in ("openai", "minimax", "deepseek", "moonshot", "grok"):
+            if self.provider in ("openai", "minimax", "deepseek", "moonshot", "grok", "openrouter"):
                 response = self._generate_openai(system_prompt, user_prompt)
             elif self.provider == "remote":
                 response = self._generate_ollama(system_prompt, user_prompt)
@@ -384,8 +393,14 @@ def _generate_response_sync(
 
             # Check if response is empty and provide diagnostics
             if not content:
+                # Prefer the classified rich message (provider + upstream +
+                # raw + action hint inline) over the bare exception string.
+                # This is what the user actually sees in the chat bubble.
+                error_info = response.get("error_info_obj")
                 error_msg = response.get("error", "")
-                if error_msg:
+                if error_info is not None:
+                    error_detail = error_info.message
+                elif error_msg:
                     error_detail = f"LLM provider returned error: {error_msg}"
                 else:
                     error_detail = (
@@ -402,8 +417,17 @@ def _generate_response_sync(
                     f"[LLM CONSECUTIVE FAILURE] Count: {self._consecutive_failures}/{self._max_consecutive_failures}"
                 )
                 if self._consecutive_failures >= self._max_consecutive_failures:
-                    raise LLMConsecutiveFailureError(self._consecutive_failures)
-                raise RuntimeError(error_detail)
+                    # Attach the underlying classified info so the agent_base
+                    # error handler can show the *cause* of the 5 failures
+                    # (e.g. "rate-limited on Google AI Studio") instead of a
+                    # meta-message about retry counts.
+                    raise LLMConsecutiveFailureError(
+                        self._consecutive_failures,
+                        last_error_info=error_info,
+                    )
+                # Use _EmptyResponse so the outer except-Exception block does NOT
+                # re-increment the counter for this same call (double-counting bug).
+                raise _EmptyResponse(error_detail)
 
             # Success - reset consecutive failure counter
             self._consecutive_failures = 0
@@ -421,6 +445,9 @@ def _generate_response_sync(
         except LLMConsecutiveFailureError:
             # Re-raise consecutive failure errors without incrementing counter
             raise
+        except _EmptyResponse as e:
+            # Failure already counted above; convert back to RuntimeError for callers.
+            raise RuntimeError(str(e)) from None
         except Exception as e:
             # Track consecutive failure for any other exception
             self._consecutive_failures += 1
@@ -428,7 +455,17 @@ def _generate_response_sync(
                 f"[LLM CONSECUTIVE FAILURE] Count: {self._consecutive_failures}/{self._max_consecutive_failures} | Error: {e}"
             )
             if self._consecutive_failures >= self._max_consecutive_failures:
-                raise LLMConsecutiveFailureError(self._consecutive_failures, last_error=e) from e
+                # Classify on the way out so the fatal-failure handler can
+                # surface the cause, not just the count.
+                try:
+                    info = classify_llm_error(e, provider=self.provider, model=self.model)
+                except Exception:
+                    info = None
+                raise LLMConsecutiveFailureError(
+                    self._consecutive_failures,
+                    last_error=e,
+                    last_error_info=info,
+                ) from e
             raise
 
     @profile("llm_generate_response", OperationCategory.LLM)
@@ -502,7 +539,7 @@ def create_session_cache(
         supports_caching = (
             (self.provider == "byteplus" and self._byteplus_cache_manager) or
             (self.provider == "gemini" and self._gemini_cache_manager) or
-            (self.provider in ("openai", "deepseek", "grok") and self.client) or  # OpenAI/DeepSeek/Grok use automatic caching with prompt_cache_key
+            (self.provider in ("openai", "deepseek", "grok", "openrouter") and self.client) or  # OpenAI/DeepSeek/Grok/OpenRouter use automatic caching with prompt_cache_key (and cache_control for Anthropic-routed OpenRouter models)
             (self.provider == "anthropic" and self._anthropic_client)  # Anthropic uses ephemeral caching with extended TTL
         )
 
@@ -605,7 +642,7 @@ def has_session_cache(self, task_id: str, call_type: str) -> bool:
                 return True
             if self.provider == "gemini" and self._gemini_cache_manager:
                 return True
-            if self.provider in ("openai", "deepseek", "grok") and self.client:
+            if self.provider in ("openai", "deepseek", "grok", "openrouter") and self.client:
                 return True
             if self.provider == "anthropic" and self._anthropic_client:
                 return True
@@ -687,8 +724,8 @@ def _generate_response_with_session_sync(
                 logger.info(f"[LLM RECV] {cleaned}")
             return cleaned
 
-        # Handle OpenAI/DeepSeek/Grok with call_type-based cache routing
-        if self.provider in ("openai", "deepseek", "grok"):
+        # Handle OpenAI/DeepSeek/Grok/OpenRouter with call_type-based cache routing
+        if self.provider in ("openai", "deepseek", "grok", "openrouter"):
             # Get stored system prompt or use provided one
             session_key = f"{task_id}:{call_type}"
             stored_system_prompt = self._session_system_prompts.get(session_key)
@@ -1184,17 +1221,50 @@ def _generate_openai(
             # Always enforce JSON output format
             request_kwargs["response_format"] = {"type": "json_object"}
 
-            # Add prompt_cache_key for OpenAI/DeepSeek cache routing.
-            # Grok (xAI) does not support prompt_cache_key — it uses automatic
-            # prefix caching and ignores this parameter, so skip it for Grok.
-            if self.provider != "grok" and call_type and system_prompt and len(system_prompt) >= config.min_cache_tokens:
+            # Build provider-specific cache hints in extra_body.
+            # - prompt_cache_key (OpenAI/DeepSeek/OpenRouter): improves prefix-cache routing
+            #   stickiness across alternating call types. Grok ignores it; we skip there
+            #   to avoid noise.
+            # - cache_control (OpenRouter routing to Anthropic Claude only): Anthropic
+            #   prompt caching is opt-in. OpenRouter accepts a top-level cache_control
+            #   field and applies it to the last cacheable block automatically. For
+            #   OpenAI/DeepSeek/Gemini upstreams via OpenRouter, caching is automatic
+            #   on the upstream side, so cache_control would be ignored — we only set
+            #   it when the slug is Anthropic-routed.
+            extra_body: Dict[str, Any] = {}
+
+            long_enough = system_prompt and len(system_prompt) >= config.min_cache_tokens
+
+            if self.provider != "grok" and call_type and long_enough:
                 prompt_hash = hashlib.sha256(system_prompt.encode()).hexdigest()[:16]
                 cache_key = f"{call_type}_{prompt_hash}"
-                request_kwargs["extra_body"] = {"prompt_cache_key": cache_key}
+                extra_body["prompt_cache_key"] = cache_key
                 logger.debug(f"[OPENAI] Using prompt_cache_key: {cache_key}")
 
+            if self.provider == "openrouter" and long_enough:
+                model_lower_for_cache = (self.model or "").lower()
+                # OpenRouter slugs are "<provider>/<model>". Anthropic Claude routes
+                # are the only ones requiring opt-in cache_control. Detect by either
+                # the slug prefix or the "claude" substring (some aliases like
+                # "anthropic/claude-3.5-sonnet:beta" still match).
+                if model_lower_for_cache.startswith("anthropic/") or "claude" in model_lower_for_cache:
+                    cache_control: Dict[str, Any] = {"type": "ephemeral"}
+                    if call_type:
+                        # 1-hour TTL keeps caches alive across alternating call types
+                        # (mirrors the Anthropic-direct path).
+                        cache_control["ttl"] = "1h"
+                    extra_body["cache_control"] = cache_control
+                    logger.debug(
+                        f"[OPENROUTER] Anthropic cache_control: {cache_control} (model={self.model})"
+                    )
+
+            if extra_body:
+                request_kwargs["extra_body"] = extra_body
+
             response = self.client.chat.completions.create(**request_kwargs)
-            content = response.choices[0].message.content.strip()
+            if not response.choices:
+                raise ValueError(f"Provider returned no choices (model={self.model!r})")
+            content = (response.choices[0].message.content or "").strip()
             token_count_input = response.usage.prompt_tokens
             token_count_output = response.usage.completion_tokens
 
@@ -1235,9 +1305,11 @@ def _generate_openai(
             token_count_output,
         )
 
-        # Report usage
+        # Report usage. service_type stays "llm_openai" (the request shape) but
+        # provider attributes to the actual upstream so dashboards split out
+        # OpenRouter / DeepSeek / Grok separately.
         self._report_usage_async(
-            "llm_openai", "openai", self.model,
+            "llm_openai", self.provider, self.model,
             token_count_input, token_count_output, cached_tokens
         )
 
@@ -1250,6 +1322,19 @@ def _generate_openai(
             # Include error details for better diagnostics
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the outer
+            # `_generate_response_sync` can attach it to the consecutive-
+            # failure exception. Without this, providers that go through
+            # this path (OpenAI, OpenRouter, Grok, DeepSeek, MiniMax,
+            # Moonshot) would surface a bare "Aborted after N consecutive
+            # failures." with no cause when they fail. The classifier is
+            # wrapped in try/except so it can never break the error path.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[OPENAI_ERROR] {error_str}")
         else:
@@ -1310,6 +1395,18 @@ def _generate_ollama(self, system_prompt: str | None, user_prompt: str) -> Dict[
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[OLLAMA_ERROR] {error_str}")
         else:
@@ -1431,6 +1528,18 @@ def _generate_gemini(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[GEMINI_ERROR] {error_str}")
         else:
@@ -1668,6 +1777,18 @@ def _generate_byteplus_standard(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[BYTEPLUS_ERROR] {error_str}")
         else:
@@ -1815,6 +1936,18 @@ def _generate_anthropic(
         if exc_obj:
             error_str = f"{type(exc_obj).__name__}: {str(exc_obj)}"
             result["error"] = error_str
+            # Classify once and stash the LLMErrorInfo object so the
+            # outer `_generate_response_sync` can put `info.message`
+            # (the rich detailed string) into the RuntimeError it raises,
+            # and attach the info to LLMConsecutiveFailureError at the
+            # 5-failure threshold. The classifier is wrapped in try/except
+            # so it can never break the error path itself.
+            try:
+                result["error_info_obj"] = classify_llm_error(
+                    exc_obj, provider=self.provider, model=self.model
+                )
+            except Exception:
+                pass
             result["content"] = ""
             logger.error(f"[ANTHROPIC_ERROR] {error_str}")
         else:
diff --git a/agent_core/core/impl/skill/manager.py b/agent_core/core/impl/skill/manager.py
index d5fc9d4d..a9e99abd 100644
--- a/agent_core/core/impl/skill/manager.py
+++ b/agent_core/core/impl/skill/manager.py
@@ -189,8 +189,12 @@ def list_skills_for_selection(self) -> Dict[str, str]:
         }
 
     # Maximum tokens for skill instructions (approximate: ~4 chars per token)
-    # This prevents skill instructions from overwhelming the context
-    MAX_SKILL_INSTRUCTIONS_TOKENS = 2000
+    # This prevents skill instructions from overwhelming the context.
+    # 16000 tokens (~64 KB of text) comfortably fits the largest single skill
+    # in the repo (~8200 tokens) plus headroom for multi-skill combos. The
+    # earlier 2000-token cap was truncating most non-trivial skills,
+    # including the workflow ones (memory-processor, craftbot-skill-*).
+    MAX_SKILL_INSTRUCTIONS_TOKENS = 16000
 
     def get_skill_instructions(self, skill_names: List[str], max_tokens: Optional[int] = None) -> str:
         """
diff --git a/agent_core/core/impl/task/manager.py b/agent_core/core/impl/task/manager.py
index 571478f1..904cbf02 100644
--- a/agent_core/core/impl/task/manager.py
+++ b/agent_core/core/impl/task/manager.py
@@ -701,6 +701,86 @@ async def _end_task(
             except Exception as e:
                 logger.warning(f"[ONBOARDING] Failed to mark soft onboarding complete: {e}")
 
+        # Skill creator/improver workflow finished — reload SkillManager so
+        # the new (or edited) skill is invocable immediately, and delete the
+        # per-task SKILL_SOURCE markdown the handler wrote.
+        if (task.workflow_id or "") in {"skill_creation", "skill_improvement"}:
+            # Always clean up the SOURCE file, regardless of completion status
+            try:
+                if self.agent_file_system_path:
+                    src_path = self.agent_file_system_path / f"SKILL_SOURCE_{task.id}.md"
+                    if src_path.exists():
+                        src_path.unlink()
+                        logger.info(f"[SKILL_CREATOR] Removed {src_path.name}")
+            except Exception as e:
+                logger.warning(f"[SKILL_CREATOR] Failed to remove SKILL_SOURCE for {task.id}: {e}")
+
+            # Reload skills only on success — a failed/cancelled task is
+            # unlikely to have left the skill in a useful state, but reloading
+            # is harmless either way. Restrict to completed for clarity.
+            if status == "completed":
+                try:
+                    from agent_core.core.impl.skill.manager import SkillManager
+                    skill_manager = SkillManager()
+                    await skill_manager.reload()
+                    logger.info(
+                        f"[SKILL_CREATOR] Reloaded skills after {task.workflow_id} task {task.id}"
+                    )
+
+                    # The freshly-discovered skill is loaded but NOT enabled
+                    # by default: skills_config.json has a non-empty
+                    # `enabled_skills` whitelist, so any skill not in that
+                    # list (or in `disabled_skills`) is treated as disabled.
+                    # Enable it so it shows up in the settings list and as a
+                    # slash command. `enable_skill` saves the config, which
+                    # the file watcher in agent_base picks up and uses to
+                    # call `sync_skill_commands` automatically.
+                    target_skill = self._extract_target_skill_name(task.instruction)
+                    if target_skill:
+                        if task.workflow_id == "skill_creation":
+                            try:
+                                if skill_manager.enable_skill(target_skill):
+                                    logger.info(
+                                        f"[SKILL_CREATOR] Enabled new skill '{target_skill}'"
+                                    )
+                                else:
+                                    logger.warning(
+                                        f"[SKILL_CREATOR] enable_skill('{target_skill}') "
+                                        f"returned False — skill may not have been written"
+                                    )
+                            except Exception as e:
+                                logger.warning(
+                                    f"[SKILL_CREATOR] enable_skill('{target_skill}') failed: {e}"
+                                )
+                        else:
+                            # improve mode: skill is already enabled; force a
+                            # config save anyway so the file watcher re-syncs
+                            # slash commands (the description / arg-hint may
+                            # have changed during the improve workflow).
+                            try:
+                                skill_manager.enable_skill(target_skill)
+                            except Exception:
+                                pass
+                except Exception as e:
+                    logger.warning(f"[SKILL_CREATOR] Skill reload failed: {e}")
+
+    @staticmethod
+    def _extract_target_skill_name(instruction: Optional[str]) -> Optional[str]:
+        """Pull the `Skill name: <name>` value out of a skill-workflow task
+        instruction. The handler in browser_adapter formats the instruction
+        with a fixed `Skill name: <name>` line; this parser is the inverse.
+        Returns None if the line is missing or malformed.
+        """
+        if not instruction:
+            return None
+        for line in instruction.splitlines():
+            stripped = line.strip()
+            if stripped.lower().startswith("skill name:"):
+                value = stripped.split(":", 1)[1].strip()
+                # Defensive — keep only kebab-case characters
+                return value or None
+        return None
+
     def _sync_state_manager(self, task: Optional[Task]) -> None:
         """Sync task state to the state manager and persist to disk."""
         if self.state_manager:
@@ -713,17 +793,21 @@ def _sync_state_manager(self, task: Optional[Task]) -> None:
                 logger.warning(f"[TaskManager] Failed to persist task {task.id}: {e}")
 
     def _log_to_task_history(self, task: Task, note: Optional[str] = None) -> None:
-        """Log completed task to TASK_HISTORY.md."""
+        """Log completed task to TASK_HISTORY.md.
+
+        Mirrors the EVENT.md / CONVERSATION_HISTORY.md pattern: just append
+        with open(..., "a"), which auto-creates the file if missing. The
+        template at app/data/agent_file_system_template/TASK_HISTORY.md
+        provides a header for users who hit Reset; users without the
+        template still get a working append-only log starting from the
+        first task completion.
+        """
         if not self.agent_file_system_path:
             return
 
         try:
             task_history_path = self.agent_file_system_path / "TASK_HISTORY.md"
 
-            if not task_history_path.exists():
-                logger.warning(f"[TaskManager] TASK_HISTORY.md not found at {task_history_path}")
-                return
-
             entry_lines = [
                 f"### Task: {task.name}",
                 f"- **Task ID:** `{task.id}`",
diff --git a/agent_core/core/impl/vlm/interface.py b/agent_core/core/impl/vlm/interface.py
index dc86d82b..240a7628 100644
--- a/agent_core/core/impl/vlm/interface.py
+++ b/agent_core/core/impl/vlm/interface.py
@@ -508,7 +508,9 @@ def _openai_describe_bytes(self, image_bytes: bytes, sys: str | None, usr: str,
             request_kwargs["max_tokens"] = 2048
 
         response = self.client.chat.completions.create(**request_kwargs)
-        content = response.choices[0].message.content.strip()
+        if not response.choices:
+            raise ValueError(f"VLM provider returned no choices (model={self.model!r})")
+        content = (response.choices[0].message.content or "").strip()
         token_count_input = response.usage.prompt_tokens
         token_count_output = response.usage.completion_tokens
         total_tokens = token_count_input + token_count_output
diff --git a/agent_core/core/llm/google_gemini_client.py b/agent_core/core/llm/google_gemini_client.py
index 114734fb..f8b73348 100644
--- a/agent_core/core/llm/google_gemini_client.py
+++ b/agent_core/core/llm/google_gemini_client.py
@@ -2,9 +2,9 @@
 """Utility client for interacting with the Google Generative Language REST API.
 
 This small helper wraps the HTTP endpoints used by Gemini so that we can
-interact with the service without pulling in the ``google-generativeai``
-package.  Using the REST interface keeps stderr free from the gRPC warnings the
-SDK emits during import/initialisation (e.g. the ``ALTS creds ignored`` message
+interact with the service without pulling in the ``google-genai`` package.
+Using the REST interface keeps stderr free from the gRPC warnings the SDK
+emits during import/initialisation (e.g. the ``ALTS creds ignored`` message
 that was polluting the CLI output).
 """
 from __future__ import annotations
diff --git a/agent_core/core/models/connection_tester.py b/agent_core/core/models/connection_tester.py
index 77925b51..6e4ed665 100644
--- a/agent_core/core/models/connection_tester.py
+++ b/agent_core/core/models/connection_tester.py
@@ -1,5 +1,14 @@
 # -*- coding: utf-8 -*-
-"""Connection tester for validating provider API keys."""
+"""Connection tester for validating provider API keys and model ids.
+
+When `model` is provided, each tester attempts a tiny chat-completion (or
+equivalent) against that exact model — so a typo in the model id is caught
+at test time, not at first real call. When `model` is omitted we fall back
+to a known-good default model from connection_test_models.json.
+
+On failure we run the underlying exception through `classify_llm_error` so
+the test result message reads exactly like a real LLM error in the chat.
+"""
 
 from typing import Dict, Any, Optional
 import httpx
@@ -11,22 +20,24 @@ def test_provider_connection(
     provider: str,
     api_key: Optional[str] = None,
     base_url: Optional[str] = None,
-    timeout: float = 10.0,
+    timeout: float = 15.0,
+    model: Optional[str] = None,
 ) -> Dict[str, Any]:
-    """Test if a provider's API key is valid by making a minimal API call.
+    """Test if a provider's API key (and optionally model id) is valid.
 
     Args:
-        provider: The LLM provider name (openai, gemini, anthropic, byteplus, remote)
-        api_key: The API key to test. If None, will check if connection is possible.
-        base_url: Optional base URL override (for byteplus/remote providers)
-        timeout: Request timeout in seconds
+        provider: The LLM provider name.
+        api_key: The API key to test.
+        base_url: Optional base URL override.
+        timeout: Request timeout in seconds.
+        model: When provided, the tester verifies this exact model is
+            reachable. Catches typos in the model id (e.g.
+            "claude-sonnet-4-5-2025092945" vs the real
+            "claude-sonnet-4-5-20250929") that would otherwise pass an
+            auth-only test and only fail at first real call.
 
     Returns:
-        Dictionary with:
-        - success: bool indicating if connection succeeded
-        - message: str with success/failure message
-        - provider: str provider name
-        - error: Optional[str] error details if failed
+        Dictionary with success/message/provider/error.
     """
     if provider not in PROVIDER_CONFIG:
         return {
@@ -40,23 +51,28 @@ def test_provider_connection(
 
     try:
         if provider == "openai":
-            return _test_openai(api_key, timeout)
+            return _test_openai(api_key, timeout, model)
         elif provider == "anthropic":
-            return _test_anthropic(api_key, timeout)
+            return _test_anthropic(api_key, timeout, model)
         elif provider == "gemini":
-            return _test_gemini(api_key, timeout)
+            return _test_gemini(api_key, timeout, model)
         elif provider == "byteplus":
             url = base_url or cfg.default_base_url
-            return _test_byteplus(api_key, url, timeout)
+            return _test_byteplus(api_key, url, timeout, model)
         elif provider == "remote":
             url = base_url or cfg.default_base_url
             return _test_remote(url, timeout)
         elif provider == "grok":
             url = cfg.default_base_url
-            return _test_grok(api_key, url, timeout)
-        elif provider in ("minimax", "deepseek", "moonshot"):
+            return _test_grok(api_key, url, timeout, model)
+        elif provider == "openrouter":
+            url = base_url or cfg.default_base_url
+            return _test_openrouter(api_key, url, timeout, model)
+        elif provider == "deepseek":
             url = cfg.default_base_url
-            return _test_openai_compat(provider, api_key, url, timeout)
+            return _test_openai_compat(provider, api_key, url, timeout, model)
+        elif provider in ("moonshot", "minimax"):
+            return _test_moonshot_minimax(provider, api_key, cfg.default_base_url, timeout, model)
         else:
             return {
                 "success": False,
@@ -73,346 +89,457 @@ def test_provider_connection(
         }
 
 
-def _test_openai(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test OpenAI API connection."""
-    if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for OpenAI",
-            "provider": "openai",
-            "error": "Missing API key",
-        }
+# ─── OpenRouter proxy helpers (Moonshot / MiniMax) ────────────────────
+
+_OR_MODEL_MAP: dict = {
+    "moonshot": {
+        "kimi-k2.5": "moonshotai/kimi-k2.5",
+        "moonshot-v1-8k": "moonshotai/moonshot-v1-8k",
+        "moonshot-v1-32k": "moonshotai/moonshot-v1-32k",
+        "moonshot-v1-128k": "moonshotai/moonshot-v1-128k",
+        "moonshot-v1-8k-vision-preview": "moonshotai/moonshot-v1-8k-vision-preview",
+    },
+    "minimax": {
+        "MiniMax-Text-01": "minimax/minimax-01",
+        "MiniMax-VL-01": "minimax/minimax-01",
+        "abab6.5s-chat": "minimax/abab6.5s-chat",
+    },
+}
+
+_OR_NAMESPACE = {"moonshot": "moonshotai", "minimax": "minimax"}
+_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+
+def _to_openrouter_slug_for_test(provider: str, model: str) -> str:
+    if "/" in model:
+        return model
+    explicit = _OR_MODEL_MAP.get(provider, {}).get(model)
+    if explicit:
+        return explicit
+    return f"{_OR_NAMESPACE.get(provider, provider)}/{model}"
 
+
+def _get_openrouter_fallback_for_test() -> tuple:
+    """Return (or_api_key, or_base_url) if OpenRouter is configured, else (None, None)."""
     try:
-        # Use models endpoint - lightweight call to verify API key
-        with httpx.Client(timeout=timeout) as client:
-            response = client.get(
-                "https://api.openai.com/v1/models",
-                headers={"Authorization": f"Bearer {api_key}"},
-            )
+        from app.config import get_api_key
+        or_key = get_api_key("openrouter") or None
+        return (or_key, _OPENROUTER_BASE_URL) if or_key else (None, None)
+    except Exception:
+        return (None, None)
 
-        if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to OpenAI API",
-                "provider": "openai",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "openai",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "openai",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
+
+def _test_moonshot_minimax(
+    provider: str,
+    api_key: Optional[str],
+    direct_url: str,
+    timeout: float,
+    model: Optional[str],
+) -> Dict[str, Any]:
+    """Test Moonshot or MiniMax.
+
+    Two distinct modes:
+    - Direct key provided: test only the provider's own endpoint. No silent
+      OR fallback — if it fails the caller gets the real error and can decide
+      whether to switch to OpenRouter.
+    - No key: try OpenRouter if configured (factory runtime-fallback path).
+    """
+    display = _DISPLAY.get(provider, provider)
+
+    if api_key:
+        # Test the direct endpoint only.  Returning OR-fallback success here
+        # would be misleading because the factory uses the direct key at runtime.
+        return _test_openai_compat(provider, api_key, direct_url, timeout, model)
+
+    # No direct key — check whether OpenRouter is configured as a fallback.
+    or_key, or_url = _get_openrouter_fallback_for_test()
+    if or_key:
+        or_model = _to_openrouter_slug_for_test(provider, model or "")
+        or_result = _test_openrouter(or_key, or_url, timeout, or_model)
+        if or_result.get("success"):
+            or_result["message"] += f" (routing {display} via OpenRouter)"
+        return or_result
+
+    return {
+        "success": False,
+        "message": f"API key is required for {display}, or configure OpenRouter as a fallback.",
+        "provider": provider,
+        "error": "No API key and OpenRouter is not configured.",
+    }
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+
+def _classified_error_result(exc: Exception, provider: str, model: Optional[str]) -> Dict[str, Any]:
+    """Run an exception through the classifier and return a failure result
+    with the rich message — same format the chat sees for real LLM errors."""
+    try:
+        from agent_core.core.impl.llm.errors import classify_llm_error
+        info = classify_llm_error(exc, provider=provider, model=model)
         return {
             "success": False,
-            "message": "Connection timed out",
-            "provider": "openai",
-            "error": "Request timed out - check your network connection",
+            "message": info.message,
+            "provider": provider,
+            "error": info.message,
         }
-    except httpx.RequestError as e:
+    except Exception:  # pragma: no cover — classifier must never break test
         return {
             "success": False,
-            "message": "Network error",
-            "provider": "openai",
-            "error": str(e),
+            "message": str(exc),
+            "provider": provider,
+            "error": str(exc),
         }
 
 
-def _test_anthropic(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test Anthropic API connection."""
+def _resolve_test_model(provider: str, model: Optional[str], fallback: str) -> str:
+    """Use the user's model when provided; otherwise pull the default test
+    model from connection_test_models.json (auth-only validation)."""
+    if model:
+        return model
+    try:
+        from app.config import get_connection_test_model
+        configured = get_connection_test_model(provider)
+        if configured:
+            return configured
+    except Exception:
+        pass
+    return fallback
+
+
+def _success(provider: str, model: Optional[str]) -> Dict[str, Any]:
+    detail = f" with model {model}" if model else ""
+    return {
+        "success": True,
+        "message": f"Successfully connected to {_DISPLAY.get(provider, provider)} API{detail}.",
+        "provider": provider,
+    }
+
+
+_DISPLAY = {
+    "openai": "OpenAI",
+    "anthropic": "Anthropic",
+    "gemini": "Google Gemini",
+    "byteplus": "BytePlus",
+    "deepseek": "DeepSeek",
+    "moonshot": "Moonshot",
+    "minimax": "MiniMax",
+    "grok": "Grok (xAI)",
+    "openrouter": "OpenRouter",
+    "remote": "Ollama",
+}
+
+
+# ─── OpenAI / OpenAI-compat ───────────────────────────────────────────
+
+
+def _openai_compat_chat_test(
+    *,
+    provider: str,
+    api_key: Optional[str],
+    base_url: Optional[str],
+    model: str,
+    timeout: float,
+) -> Dict[str, Any]:
+    """Hit /chat/completions with the user's model. The response tells us:
+        200/400/422 → key + model OK
+        401         → bad key
+        404         → bad model
+        402         → no credits (key valid)
+        429         → rate limited (key valid)
+    For all failure shapes, we surface the classifier's rich message.
+    """
     if not api_key:
         return {
             "success": False,
-            "message": "API key is required for Anthropic",
-            "provider": "anthropic",
+            "message": f"API key is required for {_DISPLAY.get(provider, provider)}",
+            "provider": provider,
             "error": "Missing API key",
         }
-
     try:
-        # Use a minimal messages request to verify API key
-        # We send an invalid request that will fail fast but verify auth
-        from app.config import get_connection_test_model, get_connection_test_config
-        test_model = get_connection_test_model("anthropic") or "claude-haiku-4-5-20251001"
-        test_config = get_connection_test_config("anthropic")
+        from openai import OpenAI
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url or None,
+            timeout=timeout,
+            max_retries=0,
+        )
+        client.chat.completions.create(
+            model=model,
+            messages=[{"role": "user", "content": "hi"}],
+            max_tokens=1,
+        )
+        return _success(provider, model)
+    except Exception as exc:
+        # 422 BadRequest with a "messages" issue still means auth+model worked.
+        # Classify, and if it's a BAD_REQUEST not about the model, treat as success.
+        from agent_core.core.impl.llm.errors import classify_llm_error, ErrorCategory
+        try:
+            info = classify_llm_error(exc, provider=provider, model=model)
+            if info.category in (ErrorCategory.AUTH, ErrorCategory.MODEL, ErrorCategory.CREDIT):
+                return {
+                    "success": False,
+                    "message": info.message,
+                    "provider": provider,
+                    "error": info.message,
+                }
+            # RATE_LIMIT, SERVER, BAD_REQUEST, etc. — auth+model are likely fine.
+            return _success(provider, model)
+        except Exception:
+            return _classified_error_result(exc, provider, model)
+
+
+def _test_openai(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
+    if model:
+        return _openai_compat_chat_test(
+            provider="openai", api_key=api_key, base_url=None, model=model, timeout=timeout,
+        )
+    # No model specified → just verify the key with /models list (cheaper).
+    if not api_key:
+        return {"success": False, "message": "API key is required for OpenAI",
+                "provider": "openai", "error": "Missing API key"}
+    try:
         with httpx.Client(timeout=timeout) as client:
-            response = client.post(
-                "https://api.anthropic.com/v1/messages",
-                headers={
-                    "x-api-key": api_key,
-                    "anthropic-version": "2023-06-01",
-                    "content-type": "application/json",
-                },
-                json={
-                    "model": test_model,
-                    "max_tokens": test_config.get("max_tokens", 1),
-                    "messages": [{"role": "user", "content": "hi"}],
-                },
+            response = client.get(
+                "https://api.openai.com/v1/models",
+                headers={"Authorization": f"Bearer {api_key}"},
             )
+        if response.status_code == 200:
+            return _success("openai", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "openai", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "openai", None)
+
 
-        # 200 means success (actual completion - shouldn't happen with max_tokens=1 but possible)
-        # 400 with specific error also indicates valid auth
+def _test_openai_compat(
+    provider: str, api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
+) -> Dict[str, Any]:
+    if model:
+        return _openai_compat_chat_test(
+            provider=provider, api_key=api_key, base_url=base_url, model=model, timeout=timeout,
+        )
+    # No model → /models list (auth-only).
+    display = _DISPLAY.get(provider, provider)
+    if not api_key:
+        return {"success": False, "message": f"API key is required for {display}",
+                "provider": provider, "error": "Missing API key"}
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(
+                f"{base_url.rstrip('/')}/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to Anthropic API",
-                "provider": "anthropic",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "anthropic",
-                "error": "Authentication failed - check your API key",
-            }
-        elif response.status_code == 400:
-            # Bad request but auth succeeded
-            return {
-                "success": True,
-                "message": "Successfully connected to Anthropic API",
-                "provider": "anthropic",
-            }
-        elif response.status_code == 529:
-            # Overloaded but auth succeeded
-            return {
-                "success": True,
-                "message": "Connected to Anthropic API (service currently overloaded)",
-                "provider": "anthropic",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "anthropic",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "anthropic",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "anthropic",
-            "error": str(e),
-        }
+            return _success(provider, None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": provider, "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, provider, None)
 
 
-def _test_gemini(api_key: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test Google Gemini API connection."""
+# ─── Anthropic ────────────────────────────────────────────────────────
+
+
+def _test_anthropic(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
     if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for Gemini",
-            "provider": "gemini",
-            "error": "Missing API key",
-        }
+        return {"success": False, "message": "API key is required for Anthropic",
+                "provider": "anthropic", "error": "Missing API key"}
 
+    test_model = _resolve_test_model("anthropic", model, fallback="claude-haiku-4-5-20251001")
+
+    try:
+        from anthropic import Anthropic
+        client = Anthropic(api_key=api_key, timeout=timeout, max_retries=0)
+        client.messages.create(
+            model=test_model,
+            max_tokens=1,
+            messages=[{"role": "user", "content": "hi"}],
+        )
+        return _success("anthropic", model)
+    except Exception as exc:
+        from agent_core.core.impl.llm.errors import classify_llm_error, ErrorCategory
+        try:
+            info = classify_llm_error(exc, provider="anthropic", model=test_model)
+            # Auth, missing model, or credit issues are real failures.
+            # 400 BadRequest about the prompt itself is fine (auth+model OK).
+            if info.category in (ErrorCategory.AUTH, ErrorCategory.MODEL, ErrorCategory.CREDIT):
+                return {
+                    "success": False,
+                    "message": info.message,
+                    "provider": "anthropic",
+                    "error": info.message,
+                }
+            return _success("anthropic", model)
+        except Exception:
+            return _classified_error_result(exc, "anthropic", model)
+
+
+# ─── Gemini ────────────────────────────────────────────────────────────
+
+
+def _test_gemini(api_key: Optional[str], timeout: float, model: Optional[str]) -> Dict[str, Any]:
+    if not api_key:
+        return {"success": False, "message": "API key is required for Gemini",
+                "provider": "gemini", "error": "Missing API key"}
+    if model:
+        # Verify the specific model via models/{name}.
+        url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}?key={api_key}"
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                response = client.get(url)
+            if response.status_code == 200:
+                return _success("gemini", model)
+            response.raise_for_status()
+            return {"success": False, "message": f"API returned status {response.status_code}",
+                    "provider": "gemini", "error": response.text[:300]}
+        except Exception as exc:
+            return _classified_error_result(exc, "gemini", model)
+    # No model → list endpoint (auth-only).
     try:
-        # Use models list endpoint to verify API key
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
                 f"https://generativelanguage.googleapis.com/v1/models?key={api_key}",
             )
-
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to Google Gemini API",
-                "provider": "gemini",
-            }
-        elif response.status_code == 400 or response.status_code == 403:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "gemini",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "gemini",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "gemini",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "gemini",
-            "error": str(e),
-        }
+            return _success("gemini", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "gemini", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "gemini", None)
+
+
+# ─── BytePlus ─────────────────────────────────────────────────────────
 
 
 def _test_byteplus(
-    api_key: Optional[str], base_url: Optional[str], timeout: float
+    api_key: Optional[str], base_url: Optional[str], timeout: float, model: Optional[str],
 ) -> Dict[str, Any]:
-    """Test BytePlus API connection."""
     if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for BytePlus",
-            "provider": "byteplus",
-            "error": "Missing API key",
-        }
-
+        return {"success": False, "message": "API key is required for BytePlus",
+                "provider": "byteplus", "error": "Missing API key"}
     url = base_url or "https://ark.ap-southeast.bytepluses.com/api/v3"
-
+    if model:
+        # Verify via tiny chat completion.
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                response = client.post(
+                    f"{url.rstrip('/')}/chat/completions",
+                    headers={
+                        "Authorization": f"Bearer {api_key}",
+                        "Content-Type": "application/json",
+                    },
+                    json={
+                        "model": model,
+                        "messages": [{"role": "user", "content": "hi"}],
+                        "max_tokens": 1,
+                    },
+                )
+            if response.status_code in (200, 400, 422):
+                # 200 = both OK. 400/422 = auth+model OK, request quirk only.
+                return _success("byteplus", model)
+            response.raise_for_status()
+            return {"success": False, "message": f"API returned status {response.status_code}",
+                    "provider": "byteplus", "error": response.text[:300]}
+        except Exception as exc:
+            return _classified_error_result(exc, "byteplus", model)
+    # No model → /models list.
     try:
-        # BytePlus uses OpenAI-compatible API, test with models endpoint
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
                 f"{url.rstrip('/')}/models",
                 headers={"Authorization": f"Bearer {api_key}"},
             )
-
         if response.status_code == 200:
-            return {
-                "success": True,
-                "message": "Successfully connected to BytePlus API",
-                "provider": "byteplus",
-            }
-        elif response.status_code == 401:
-            return {
-                "success": False,
-                "message": "Invalid API key",
-                "provider": "byteplus",
-                "error": "Authentication failed - check your API key",
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"API returned status {response.status_code}",
-                "provider": "byteplus",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "byteplus",
-            "error": "Request timed out - check your network connection",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "byteplus",
-            "error": str(e),
-        }
+            return _success("byteplus", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "byteplus", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "byteplus", None)
+
+
+# ─── Remote (Ollama) ──────────────────────────────────────────────────
 
 
 def _test_remote(base_url: Optional[str], timeout: float) -> Dict[str, Any]:
-    """Test remote/Ollama connection (no API key required)."""
+    """No API key required; the UI already validates Ollama models via
+    the /api/tags dropdown, so this stays auth-equivalent."""
     url = base_url or "http://localhost:11434"
-
     try:
-        # Ollama uses /api/tags to list models
         with httpx.Client(timeout=timeout) as client:
             response = client.get(f"{url.rstrip('/')}/api/tags")
-
         if response.status_code == 200:
             models = [m["name"] for m in response.json().get("models", [])]
             if models:
                 message = f"Connected! {len(models)} model(s) available: {', '.join(models)}"
             else:
                 message = "Connected to Ollama, but no models downloaded yet. Use '+ Download New Model' to get one."
-            return {
-                "success": True,
-                "message": message,
-                "provider": "remote",
-                "models": models,
-            }
-        else:
-            return {
-                "success": False,
-                "message": f"Ollama returned status {response.status_code}",
-                "provider": "remote",
-                "error": response.text[:200] if response.text else "Unknown error",
-            }
-    except httpx.TimeoutException:
-        return {
-            "success": False,
-            "message": "Connection timed out",
-            "provider": "remote",
-            "error": f"Could not connect to Ollama at {url}. Is it running?",
-        }
-    except httpx.RequestError as e:
-        return {
-            "success": False,
-            "message": "Network error",
-            "provider": "remote",
-            "error": f"Could not connect to {url}: {str(e)}",
-        }
+            return {"success": True, "message": message, "provider": "remote", "models": models}
+        return {"success": False, "message": f"Ollama returned status {response.status_code}",
+                "provider": "remote", "error": response.text[:200] if response.text else "Unknown error"}
+    except Exception as exc:
+        return _classified_error_result(exc, "remote", None)
 
 
-def _test_openai_compat(
-    provider: str, api_key: Optional[str], base_url: str, timeout: float
-) -> Dict[str, Any]:
-    """Test an OpenAI-compatible API (MiniMax, DeepSeek, Moonshot)."""
-    names = {"minimax": "MiniMax", "deepseek": "DeepSeek", "moonshot": "Moonshot", "grok": "Grok (xAI)"}
-    display = names.get(provider, provider)
+# ─── OpenRouter ───────────────────────────────────────────────────────
 
-    if not api_key:
-        return {
-            "success": False,
-            "message": f"API key is required for {display}",
-            "provider": provider,
-            "error": "Missing API key",
-        }
 
+def _test_openrouter(
+    api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
+) -> Dict[str, Any]:
+    if not api_key:
+        return {"success": False, "message": "API key is required for OpenRouter",
+                "provider": "openrouter", "error": "Missing API key"}
+    if model:
+        # Verify auth + model + credits via tiny chat completion. OR returns
+        # 401 (bad key), 402 (no credits), 404 (bad model slug), or 200/4xx
+        # depending on upstream. Classifier handles them all.
+        return _openai_compat_chat_test(
+            provider="openrouter", api_key=api_key, base_url=base_url, model=model, timeout=timeout,
+        )
+    # No model → /auth/key (auth + balance only).
     try:
         with httpx.Client(timeout=timeout) as client:
             response = client.get(
-                f"{base_url.rstrip('/')}/models",
+                f"{base_url.rstrip('/')}/auth/key",
                 headers={"Authorization": f"Bearer {api_key}"},
             )
-
         if response.status_code == 200:
-            return {"success": True, "message": f"Successfully connected to {display} API", "provider": provider}
-        elif response.status_code in (401, 403):
-            return {"success": False, "message": "Invalid API key", "provider": provider, "error": f"Authentication failed (HTTP {response.status_code}) - check your API key"}
-        else:
-            return {"success": False, "message": f"API returned status {response.status_code}", "provider": provider, "error": response.text[:300] if response.text else "Unknown error"}
-    except httpx.TimeoutException:
-        return {"success": False, "message": "Connection timed out", "provider": provider, "error": "Request timed out - check your network connection"}
-    except httpx.RequestError as e:
-        return {"success": False, "message": "Network error", "provider": provider, "error": str(e)}
+            data = response.json().get("data", {}) or {}
+            limit = data.get("limit")
+            usage = data.get("usage")
+            label = data.get("label") or "OpenRouter key"
+            if limit is None:
+                msg = f"Connected to OpenRouter ({label}) — unlimited credits"
+            else:
+                remaining = max(0.0, float(limit) - float(usage or 0.0))
+                msg = (f"Connected to OpenRouter ({label}) — "
+                       f"${remaining:.2f} of ${float(limit):.2f} remaining")
+            return {"success": True, "message": msg, "provider": "openrouter"}
+        if response.status_code in (401, 403):
+            return {"success": False, "message": "Invalid API key",
+                    "provider": "openrouter",
+                    "error": "Authentication failed - check your OpenRouter API key"}
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "openrouter", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "openrouter", None)
 
 
-def _test_grok(api_key: Optional[str], base_url: str, timeout: float) -> Dict[str, Any]:
-    """Test xAI Grok API connection using a minimal chat completion request.
+# ─── Grok ─────────────────────────────────────────────────────────────
 
-    xAI returns 403 on the /models endpoint even for valid keys, so we use
-    a minimal chat completions call instead.
-    """
-    if not api_key:
-        return {
-            "success": False,
-            "message": "API key is required for Grok (xAI)",
-            "provider": "grok",
-            "error": "Missing API key",
-        }
 
+def _test_grok(
+    api_key: Optional[str], base_url: str, timeout: float, model: Optional[str],
+) -> Dict[str, Any]:
+    if not api_key:
+        return {"success": False, "message": "API key is required for Grok (xAI)",
+                "provider": "grok", "error": "Missing API key"}
+    test_model = _resolve_test_model("grok", model, fallback="grok-3")
     try:
         with httpx.Client(timeout=timeout) as client:
             response = client.post(
@@ -422,22 +549,18 @@ def _test_grok(api_key: Optional[str], base_url: str, timeout: float) -> Dict[st
                     "Content-Type": "application/json",
                 },
                 json={
-                    "model": "grok-3",
+                    "model": test_model,
                     "max_tokens": 1,
                     "messages": [{"role": "user", "content": "hi"}],
                 },
             )
-
-        if response.status_code in (200, 400, 403, 422):
-            # 200 = success
-            # 400/422 = bad request but auth passed
-            # 403 = model tier restriction but key is valid
-            return {"success": True, "message": "Successfully connected to Grok (xAI) API", "provider": "grok"}
-        elif response.status_code == 401:
-            return {"success": False, "message": "Invalid API key", "provider": "grok", "error": "Authentication failed - check your xAI API key"}
-        else:
-            return {"success": False, "message": f"API returned status {response.status_code}", "provider": "grok", "error": response.text[:300] if response.text else "Unknown error"}
-    except httpx.TimeoutException:
-        return {"success": False, "message": "Connection timed out", "provider": "grok", "error": "Request timed out - check your network connection"}
-    except httpx.RequestError as e:
-        return {"success": False, "message": "Network error", "provider": "grok", "error": str(e)}
+        if response.status_code == 200:
+            return _success("grok", model)
+        if response.status_code in (400, 422) and model is None:
+            # Hardcoded test model probably hit a tier restriction; auth still OK.
+            return _success("grok", None)
+        response.raise_for_status()
+        return {"success": False, "message": f"API returned status {response.status_code}",
+                "provider": "grok", "error": response.text[:300]}
+    except Exception as exc:
+        return _classified_error_result(exc, "grok", model)
diff --git a/agent_core/core/models/factory.py b/agent_core/core/models/factory.py
index 7c654c58..d9db68ad 100644
--- a/agent_core/core/models/factory.py
+++ b/agent_core/core/models/factory.py
@@ -19,6 +19,54 @@
 
 logger = logging.getLogger(__name__)
 
+# Providers that should route through OpenRouter when OR is configured,
+# because their direct APIs are geo-restricted for most international users.
+_OPENROUTER_PROXIED = {"moonshot", "minimax"}
+
+# OpenRouter namespace per provider (for auto-slugging unknown model IDs).
+_OR_NAMESPACE = {
+    "moonshot": "moonshotai",
+    "minimax": "minimax",
+}
+
+# Explicit model-ID → OpenRouter slug overrides.
+_OR_MODEL_MAP: dict = {
+    "moonshot": {
+        "kimi-k2.5": "moonshotai/kimi-k2.5",
+        "moonshot-v1-8k": "moonshotai/moonshot-v1-8k",
+        "moonshot-v1-32k": "moonshotai/moonshot-v1-32k",
+        "moonshot-v1-128k": "moonshotai/moonshot-v1-128k",
+        "moonshot-v1-8k-vision-preview": "moonshotai/moonshot-v1-8k-vision-preview",
+    },
+    "minimax": {
+        "MiniMax-Text-01": "minimax/minimax-01",
+        "MiniMax-VL-01": "minimax/minimax-01",
+        "abab6.5s-chat": "minimax/abab6.5s-chat",
+    },
+}
+
+_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
+
+
+def _to_openrouter_slug(provider: str, model: str) -> str:
+    """Convert a provider-native model ID to its OpenRouter slug."""
+    if "/" in model:
+        return model
+    explicit = _OR_MODEL_MAP.get(provider, {}).get(model)
+    if explicit:
+        return explicit
+    namespace = _OR_NAMESPACE.get(provider, provider)
+    return f"{namespace}/{model}"
+
+
+def _get_openrouter_key() -> Optional[str]:
+    """Return the stored OpenRouter API key, or None if not configured."""
+    try:
+        from app.config import get_api_key
+        return get_api_key("openrouter") or None
+    except Exception:
+        return None
+
 
 def _resolve_ollama_model(requested: str, base_url: str) -> str:
     """Return `requested` if Ollama has it, otherwise return the first available model."""
@@ -65,7 +113,7 @@ def create(
             Dictionary with provider context including client instances
         """
         # OpenAI-compatible providers that use OpenAI client with a custom base_url
-        _OPENAI_COMPAT = {"minimax", "deepseek", "moonshot", "grok"}
+        _OPENAI_COMPAT = {"minimax", "deepseek", "moonshot", "grok", "openrouter"}
 
         if provider not in PROVIDER_CONFIG:
             raise ValueError(f"Unsupported provider: {provider}")
@@ -176,6 +224,29 @@ def create(
             }
 
         if provider in _OPENAI_COMPAT:
+            # Moonshot and MiniMax are geo-restricted for most international users.
+            # Strategy:
+            #   1. If a direct API key is provided → use the provider's own endpoint.
+            #   2. If no direct key but OpenRouter is configured → proxy through OR.
+            #   3. Otherwise → raise / defer as usual.
+            if provider in _OPENROUTER_PROXIED and not api_key:
+                or_key = _get_openrouter_key()
+                if or_key:
+                    or_model = _to_openrouter_slug(provider, model)
+                    logger.info(
+                        f"[FACTORY] No direct key for {provider} — routing through OpenRouter as {or_model}"
+                    )
+                    return {
+                        "provider": "openrouter",
+                        "model": or_model,
+                        "client": OpenAI(api_key=or_key, base_url=_OPENROUTER_BASE_URL),
+                        "gemini_client": None,
+                        "remote_url": None,
+                        "byteplus": None,
+                        "anthropic_client": None,
+                        "initialized": True,
+                    }
+
             if not api_key:
                 if deferred:
                     return empty_context
diff --git a/agent_core/core/models/model_registry.py b/agent_core/core/models/model_registry.py
index f63c365c..309b7c69 100644
--- a/agent_core/core/models/model_registry.py
+++ b/agent_core/core/models/model_registry.py
@@ -31,7 +31,7 @@
     },
     "minimax": {
         InterfaceType.LLM: "MiniMax-Text-01",
-        InterfaceType.VLM: None,
+        InterfaceType.VLM: "MiniMax-VL-01",
         InterfaceType.EMBEDDING: None,
     },
     "deepseek": {
@@ -40,8 +40,8 @@
         InterfaceType.EMBEDDING: None,
     },
     "moonshot": {
-        InterfaceType.LLM: "moonshot-v1-8k",
-        InterfaceType.VLM: None,
+        InterfaceType.LLM: "kimi-k2.5",
+        InterfaceType.VLM: "moonshot-v1-8k-vision-preview",
         InterfaceType.EMBEDDING: None,
     },
     "grok": {
@@ -49,4 +49,11 @@
         InterfaceType.VLM: "grok-4-0709",
         InterfaceType.EMBEDDING: None,
     },
+    "openrouter": {
+        # OpenRouter slugs follow `<provider>/<model>` format. Default to a Claude
+        # model so KV caching exercises the cache_control path on first use.
+        InterfaceType.LLM: "anthropic/claude-sonnet-4.5",
+        InterfaceType.VLM: "anthropic/claude-sonnet-4.5",
+        InterfaceType.EMBEDDING: None,
+    },
 }
diff --git a/agent_core/core/models/provider_config.py b/agent_core/core/models/provider_config.py
index c948ded1..2c8de6bd 100644
--- a/agent_core/core/models/provider_config.py
+++ b/agent_core/core/models/provider_config.py
@@ -41,4 +41,9 @@ class ProviderConfig:
         api_key_env="XAI_API_KEY",
         default_base_url="https://api.x.ai/v1",
     ),
+    "openrouter": ProviderConfig(
+        api_key_env="OPENROUTER_API_KEY",
+        base_url_env="OPENROUTER_BASE_URL",
+        default_base_url="https://openrouter.ai/api/v1",
+    ),
 }
diff --git a/agent_core/core/prompts/action.py b/agent_core/core/prompts/action.py
index d5e38203..793d22f9 100644
--- a/agent_core/core/prompts/action.py
+++ b/agent_core/core/prompts/action.py
@@ -69,12 +69,35 @@
 - Check USER.md for "Preferred Messaging Platform" setting when notifying user.
 - For notifications about third-party messages, use preferred platform if available.
 - If preferred platform's send action is unavailable, fall back to send_message (interface).
+
+Self-Awareness Before Asking the User:
+- Before asking the user for ANY information about your own configuration (connected accounts, credentials, integration setup, file paths, available skills, MCP servers), you MUST first try to find the answer yourself:
+  1. Call introspection actions: list_available_integrations, check_integration_status, list_action_sets, list_skills.
+  2. Read AGENT.md (it documents how you work and what's wired up).
+  3. Read configuration of your own in app/config/.
+- Only ask the user if all three sources fail to provide the answer.
 </rules>
 
 <parallel_actions>
-You MAY start multiple independent tasks in parallel by including multiple task_start actions.
-Example: User asks "research topic A and topic B" → start both tasks simultaneously.
-You MAY parallelize task_start actions. send message action can run with other actions but do not use multiple send message action actions simultaneously - combine into one message. ignore must run alone.
+STRICT RULE — Same-type parallelism only:
+- You MUST NOT combine actions of DIFFERENT types in a single step.
+- The ONLY parallelism allowed in conversation mode is multiple task_start actions together (e.g. task_start + task_start + task_start).
+- All other actions MUST run alone in their own step.
+
+FORBIDDEN combinations (never do these):
+- task_start + send_message (or any platform send action)
+- task_start + ignore
+- send_message + ignore
+- send_message + any other action
+- ignore + any other action
+- Any mix of two different action types
+
+ALLOWED:
+- A single action by itself (default case).
+- Multiple task_start actions together — same type only.
+  Example: User asks "research topic A and topic B" → two task_start actions in the same step.
+
+Rationale: pairing task_start with a send_message that has wait_for_user_reply=true causes the task to be created and immediately parked, so it never executes. If you need to acknowledge or ask a clarifying question, do it AFTER the task starts (inside the task), not alongside task_start.
 </parallel_actions>
 
 <notes>
@@ -144,6 +167,8 @@
 ---
 
 {event_stream}
+
+{integration_essentials}
 """
 
 # Used in User Prompt when asking the model to select an action from the list of candidates
@@ -358,6 +383,8 @@
 ---
 
 {event_stream}
+
+{integration_essentials}
 """
 
 # Compact action space prompt for GUI mode (UI-TARS style)
@@ -546,6 +573,8 @@
 {memory_context}
 
 {event_stream}
+
+{integration_essentials}
 """
 
 __all__ = [
diff --git a/agent_core/core/prompts/context.py b/agent_core/core/prompts/context.py
index a8a00b0a..7dc5d120 100644
--- a/agent_core/core/prompts/context.py
+++ b/agent_core/core/prompts/context.py
@@ -205,7 +205,7 @@
 IMPORTANT: Always use absolute paths when working with files in the agent file system.
 
 ## Core Files
-- **{agent_file_system_path}/AGENT.md**: Your identity file containing agent configuration, operating model, task execution guidelines, communication rules, error handling strategies, documentation standards, and organization context including org chart.
+- **{agent_file_system_path}/AGENT.md**: Your identity file containing agent configuration, operating model, task execution guidelines, communication rules, error handling strategies, documentation standards, and organization context including org chart. Use this to understand how yourself work when user is asking about your feature/mechanism that you have no context of.
 - **{agent_file_system_path}/USER.md**: User profile containing identity, communication preferences, interaction settings, and personality information. Reference this to personalize interactions.
 - **{agent_file_system_path}/SOUL.md**: Your personality, tone, and behavioral traits. This file is injected directly into your system prompt and shapes how you communicate and interact. Users can edit it to customize your personality. You can read and update SOUL.md to adjust your personality when instructed by the user.
 - **{agent_file_system_path}/MEMORY.md**: Persistent memory log storing distilled facts, preferences, and events from past interactions. Format: `[timestamp] [type] content`. Agent should NOT edit directly - use memory processing actions.
@@ -221,6 +221,10 @@
 - **{agent_file_system_path}/workspace/tmp/{{task_id}}/**: Temporary directory for task specific temp files (e.g., plan, draft, sketch pad). These directories are automatically cleaned up when tasks end or when the agent starts.
 - **{agent_file_system_path}/workspace/missions/**: Dedicated folders for missions (work spanning multiple tasks). Each mission has an INDEX.md for context continuity. Scan this directory at the start of complex tasks.
 
+## Skills Directory
+- **{skills_path}/**: The ONLY location for skill files and skill assets. Each skill lives in its own subfolder `{skills_path}/<skill_name>/` containing a `SKILL.md` and any supporting files the skill needs (scripts, templates, references, etc.).
+- IMPORTANT: Skills MUST NOT be stored, copied, or moved outside of the `{skills_path}/` folder. When creating, installing, editing, or generating any skill-related files, they MUST reside under `{skills_path}/<skill_name>/`.
+
 ## Important Notes
 - ALWAYS use absolute paths (e.g., {agent_file_system_path}/workspace/report.pdf) when referencing files
 - Save files to `{agent_file_system_path}/workspace/` directory if you want to persist them after task ended or across tasks
diff --git a/agent_core/core/prompts/routing.py b/agent_core/core/prompts/routing.py
index ac18b7f4..932d0ddd 100644
--- a/agent_core/core/prompts/routing.py
+++ b/agent_core/core/prompts/routing.py
@@ -7,13 +7,18 @@
 
 # --- Unified Session Routing ---
 # This prompt is the LAST-RESORT routing decision. The chat handler short-circuits
-# the easy cases deterministically (explicit UI reply target, third-party
-# notifications, single waiting task, reply markers) BEFORE this prompt runs.
-# By the time the LLM sees the message, those cases are already handled.
+# the easy cases (explicit UI reply target, third-party notifications, reply
+# markers) before this prompt runs.
 #
-# The prompt's job: decide if a message in main chat with active task(s) is
-# CLEARLY a continuation/modification of one of those tasks, or a new request.
-# Default to NEW SESSION when in doubt.
+# The prompt's job: with one or more active tasks, decide whether the incoming
+# message is unambiguously linked to one of them (continuation, modification,
+# cancellation, answer to its question, or Living UI reference) or is a fresh
+# request that deserves a new session. Default to NEW when in doubt.
+#
+# A waiting task's approval-seeking question ("is this acceptable?") plus a
+# user reply containing approval language ("thanks", "looks good") IS the
+# task_end signal that task is parked for — the prompt is explicit about this
+# so the LLM does not misfile it as conversational chatter.
 ROUTE_TO_SESSION_PROMPT = """
 <objective>
 You are a session router. Decide whether an incoming message is a clear continuation
@@ -38,56 +43,34 @@
 </recent_conversation>
 
 <rules>
-DEFAULT: create a new session. When in doubt, choose "new".
-
-Route to an existing session ONLY IF the message clearly fits ONE of these:
-  - References a specific file, output, or artifact created by that task
-    (e.g. "the PDF you made", "the translated report", a filename produced by that task)
-  - Is a clear modification of that task's original instruction
-    (e.g. "translate to Spanish instead", "also include X", "skip page 5", "make it shorter")
-  - Cancels or pauses that task explicitly
-    (e.g. "stop the translation", "pause the report", "cancel that task")
-  - Is a context-dependent message ("fix this", "it's broken", "add a feature")
-    AND there is an active task whose Living UI ID matches the user's current
-    Living UI page (see <incoming_item> above)
-  - Explicitly names a Living UI app/project that matches one of the active
-    tasks' Living UI bindings — even if the user is currently viewing a
-    different Living UI page. Chat is global; the user can talk about any
-    Living UI from anywhere.
-
-DO NOT route based on:
-  - "There's only one active task" — single active task is NOT a reason to route
-    a generic message to it. This bias previously caused multiple wrong-routing bugs.
-  - Generic acknowledgments ("thanks", "ok", "got it", "yes", "no") — these are
-    conversational. Create a new session.
-  - Topic resemblance alone — "I want to translate something" while a translate
-    task is running is a NEW request, not a modification of the active task,
-    unless the user explicitly says so.
-  - "[REPLYING TO PREVIOUS AGENT MESSAGE]:" markers — those are handled before
-    this prompt runs and won't reach you.
+DEFAULT: new session. Route to an existing session S ONLY when the message
+has an unambiguous link to S.
 
-Living UI specifics:
-  - The user's current Living UI page is a CONTEXT hint, not a hard binding.
-  - For context-dependent messages with no explicit reference, prefer the task
-    bound to the user's current Living UI.
-  - For messages that explicitly name a different Living UI (by app name, project
-    path, or feature description that clearly belongs to that other Living UI),
-    route to THAT Living UI's task instead.
-  - If no active task matches the referenced Living UI, choose new session.
+Route to S when the message:
+1. Names an artifact / file / output S produced.
+2. Modifies, narrows, or cancels S's instruction.
+3. Answers a question S's last agent message asked. Critical case: if S is
+   WAITING FOR REPLY and its last outbound sought approval or change
+   feedback (e.g. "is this acceptable?", "does this look good?", "want
+   changes?"), then approval phrases — "thanks", "looks good", "it's good",
+   "done", "that's all", including thanks-wrapped variants like
+   "thanks, looks good" or "thanks for X, it's good" — ARE that answer.
+   This is the task_end approval S is parked for; do not misclassify as
+   conversational.
+4. Living UI: context-free reference ("fix this", "it broke") AND S's
+   Living UI ID matches the user's current page; OR the message explicitly
+   names a Living UI matching S's binding (chat is global, any page).
 
-Using <recent_conversation>:
-  - It tells you what was just discussed across the whole agent (not just one
-    task). Use it to disambiguate context-dependent messages — e.g., "and
-    Spanish" makes sense if the previous message was about translation.
-  - If the recent conversation shows a task topic that has already COMPLETED
-    (no longer in <existing_sessions>), prefer creating a new session over
-    routing to an unrelated active task. The completed task can't be resumed.
-  - If the recent conversation contains nothing relevant, treat the message
-    purely on its own merits per the rules above.
+Insufficient → new session:
+- S exists, or is the only active task.
+- Same topic as S without an explicit reference.
+- S's last outbound is only a generic close-out ("anything else?",
+  "let me know if needed") — close-outs are not routable questions; an
+  unrelated follow-up is a new session.
 
-The "agent asked a question, user is answering" case is handled
-deterministically before this prompt runs (via the waiting_for_user_reply flag).
-You do NOT need to consider it.
+recent_conversation resolves ambiguous references. If the relevant topic is
+in a COMPLETED task (absent from existing_sessions), choose NEW —
+completed sessions cannot resume.
 </rules>
 
 <output_format>
diff --git a/agent_core/core/state/session.py b/agent_core/core/state/session.py
index 7aae45f3..79b29c49 100644
--- a/agent_core/core/state/session.py
+++ b/agent_core/core/state/session.py
@@ -72,6 +72,13 @@ def start(
     ) -> "StateSession":
         """Create or update a session for the given session_id.
 
+        If a session already exists for this session_id, its `agent_properties`
+        (which hold per-task counters like action_count and token_count) are
+        preserved across re-entries. Only the session context fields (task,
+        event_stream, gui_mode) are refreshed. Counters are reset only at task
+        end via StateSession.end(), or explicitly when the user resumes past a
+        limit.
+
         Args:
             session_id: Unique identifier for this session (typically task_id)
             current_task: The Task object for this session
@@ -81,6 +88,14 @@ def start(
         Returns:
             The created or updated StateSession instance
         """
+        existing = cls._instances.get(session_id)
+        if existing is not None:
+            existing.current_task = current_task
+            existing.event_stream = event_stream
+            existing.gui_mode = gui_mode
+            existing.agent_properties.set_property("current_task_id", session_id)
+            return existing
+
         inst = cls()
         inst.session_id = session_id
         inst.current_task = current_task
diff --git a/agent_core/core/task/task.py b/agent_core/core/task/task.py
index c90c3a21..1d832c2f 100644
--- a/agent_core/core/task/task.py
+++ b/agent_core/core/task/task.py
@@ -65,6 +65,10 @@ class Task:
     # Per-task counters (persisted across trigger cycles, CraftBot)
     action_count: int = 0
     token_count: int = 0
+    # Per-task LLM token usage breakdown (CraftBot, updated per LLM call)
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_tokens: int = 0
     # UUID for the task-level "divisible" action on the chatserver (CraftBot)
     chatserver_action_id: Optional[str] = None
     # Whether the task is waiting for user reply (pauses trigger scheduling)
@@ -117,6 +121,9 @@ def to_dict(self) -> Dict[str, Any]:
             "conversation_id": self.conversation_id,
             "action_count": self.action_count,
             "token_count": self.token_count,
+            "input_tokens": self.input_tokens,
+            "output_tokens": self.output_tokens,
+            "cache_tokens": self.cache_tokens,
             "chatserver_action_id": self.chatserver_action_id,
             "waiting_for_user_reply": self.waiting_for_user_reply,
             "source_platform": self.source_platform,
@@ -145,6 +152,9 @@ def from_dict(cls, data: Dict[str, Any]) -> "Task":
             conversation_id=data.get("conversation_id"),
             action_count=data.get("action_count", 0),
             token_count=data.get("token_count", 0),
+            input_tokens=data.get("input_tokens", 0),
+            output_tokens=data.get("output_tokens", 0),
+            cache_tokens=data.get("cache_tokens", 0),
             chatserver_action_id=data.get("chatserver_action_id"),
             waiting_for_user_reply=data.get("waiting_for_user_reply", False),
             source_platform=data.get("source_platform"),
diff --git a/agent_file_system/AGENT.md b/agent_file_system/AGENT.md
index 910a24a6..9e88863b 100644
--- a/agent_file_system/AGENT.md
+++ b/agent_file_system/AGENT.md
@@ -1,152 +1,4538 @@
-# Agent Identity
-
-You are a general-purpose personal assistant AI agent developed by CraftOS.
-Your primary role is to assist users with ANY computer-based tasks. You can execute commands, manipulate files, browse the web, interact with applications, and complete complex multi-step workflows autonomously.
-You are not a chatbot. You are an autonomous agent that takes actions to accomplish goals. When given a task, you plan, execute, validate, and iterate until the goal is achieved or you determine it cannot be completed.
-
-## Error Handling
-
-Errors are normal. How you handle them determines success.
-- When an action fails, first understand why. Check the error message and the event stream. Is it a temporary issue that might succeed on retry? Is it a fundamental problem with your approach? Is it something outside your control?
-- For temporary failures (network issues, timing problems), a retry may work. But do not retry blindly - wait a moment, or try with slightly different parameters.
-- For approach failures (wrong action, incorrect parameters, misunderstanding of the task), change your approach. Select a different action or reformulate your plan.
-- For impossible tasks (required access you do not have, physical actions needed, policy violations), stop and inform the user. Explain what you tried, why it cannot work, and suggest alternatives if any exist.
-- If you find yourself stuck in a loop - the same action failing repeatedly with the same error - recognize this pattern and break out. Either try a fundamentally different approach or inform the user that you are blocked.
-- Never continue executing actions indefinitely when they are not making progress. This wastes resources and frustrates users.
-
-## File Handling
-
-Efficient File Reading:
-- read_file returns content with line numbers (cat -n format)
-- Default limit is 2000 lines - check has_more in response to know if file continues
-- For large files (>500 lines), follow this strategy:
-  1. Read beginning first to understand structure
-  2. Use grep_files to find specific patterns/functions
-  3. Use read_file with offset/limit to read targeted sections based on grep results
-
-File Actions:
-- read_file: General reading with pagination (offset/limit)
-- grep_files: Search files/directories for regex patterns with three output modes: 'files_with_matches' (discover files), 'content' (matching lines with line numbers), 'count' (match counts). Supports glob/file_type filtering, before/after context lines, case_insensitive, and multiline.
-- stream_read + stream_edit: Use together for file modifications
-
-Avoid: Reading entire large files repeatedly - use grep + targeted offset/limit reads instead
-
-## Self-Improvement Protocol
-
-You are a self-improving agent. When you encounter a capability gap, proactively expand your abilities using the following mechanisms.
-
-### Self-Improvement Workflow
-When you CANNOT complete a task due to missing capabilities:
-1. IDENTIFY - What capability is missing?
-2. SEARCH - Use `web_search` to find MCP servers or skills that provide the capability
-3. INSTALL - Edit config files or clone repositories to install the solution
-4. WAIT - The system will automatically detect the file change and hot-reload the new capability
-5. CONTINUE - Proceed with the task using the new capability
-6. REMEMBER - Store the solution in memory for future reference
-
-IMPORTANT: Always inform the user when you install new capabilities. Ask for permission if the installation requires credentials or has security implications.
-
-### Automatic Hot-Reload
-All configuration files are monitored for changes. When you edit any config file, the system automatically detects the change and reloads the configuration within ~1 second. No manual reload actions or restart required.
-
-Monitored config files:
-- `app/config/settings.json` - Settings (API keys, model config, OAuth credentials)
-- `app/config/mcp_config.json` - MCP server connections
-- `app/config/skills_config.json` - Skill configurations
-- `app/config/external_comms_config.json` - Communication platform integrations
-
-### 1. MCP - Install New Tools
-Config file: `app/config/mcp_config.json`
-
-When you lack a capability (e.g., cannot access a service, need a specific tool):
-1. Use `read_file` to check existing MCP servers in `app/config/mcp_config.json`
-2. Use `web_search` to find MCP servers: search "<capability> MCP server" or "modelcontextprotocol <service>"
-3. Use `stream_edit` to add new server entry to the `mcp_servers` array in `app/config/mcp_config.json`
-4. Set `"enabled": true` to activate the server
-5. The system will automatically detect the change and connect to the new server
-
-MCP server entry format:
-```json
-{
-  "name": "server-name",
-  "description": "What this server does",
-  "transport": "stdio",
-  "command": "npx",
-  "args": ["-y", "@org/server-package"],
-  "env": {"API_KEY": ""},
-  "enabled": true
+---
+version: 3
+purpose: agent operations manual
+---
+
+# AGENT.md
+
+Your ops manual. Grep `## <topic>` to load what you need.
+
+## Index
+
+<!-- index -->
+```
+add MCP server          → ## MCP
+add skill               → ## Skills
+connect platform        → ## Integrations
+use an integration      → ## Integrations  (and grep its INTEGRATION.md)
+switch model            → ## Models
+set API key             → ## Models
+generate document       → ## Documents
+build Living UI         → ## Living UI
+schedule recurring task → ## Proactive
+edit config file        → ## Configs
+start a task            → ## Tasks
+handle an error         → ## Errors
+read / edit a file      → ## Files
+discover an action      → ## Actions
+persistent storage      → ## File System
+long-running work       → ## Workspace
+self-improve            → ## Self-Improvement
+edit AGENT/USER/SOUL.md → ## Self-Edit
+look up a term          → ## Glossary
+```
+<!-- /index -->
+
+---
+
+## Runtime
+
+You run inside `AgentBase.react(trigger)` at [app/agent_base.py](app/agent_base.py). Each turn: one trigger is consumed, the LLM picks one or more actions, the executor runs them, events are appended to streams, and (often) a new trigger is queued for the next turn.
+
+### Trigger anatomy
+
+Triggers live in a priority queue at [agent_core/core/impl/trigger/queue.py](agent_core/core/impl/trigger/queue.py), ordered by `fire_at` (Unix timestamp) then `priority` (lower number = higher priority). Each trigger carries:
+
+```
+fire_at:                  float    when it should fire
+priority:                 int      ordering within same fire_at
+next_action_description:  str      human-readable hint
+payload:                  dict     routing + context
+session_id:               str|None which session/task this belongs to
+waiting_for_reply:        bool     paused for user input
+```
+
+`payload.type` is the routing key:
+```
+"memory_processing"   → memory workflow      (creates a memory-processor task)
+"proactive_heartbeat" → proactive heartbeat  (creates a Heartbeat task)
+"proactive_planner"   → proactive planner    (creates a day/week/month planner task)
+<absent or other>     → falls through to task / conversation routing by session state
+```
+
+Trigger producers:
+- The scheduler ([app/config/scheduler_config.json](app/config/scheduler_config.json)) — fires `memory_processing`, `proactive_heartbeat`, `proactive_planner` on cron.
+- External-comms listeners and the UI — fire triggers carrying user messages in the payload.
+- Actions you invoke — `wait`, `task_end`, and others enqueue follow-up triggers via `triggers.put(...)`.
+
+### react() routing (in order)
+
+```
+1.  _is_memory_trigger(trigger)        → _handle_memory_workflow         → return
+2.  _is_proactive_trigger(trigger)     → _handle_proactive_workflow      → return
+3.  _extract_trigger_data(trigger)
+4.  _initialize_session(...)
+5.  record user_message in trigger payload (if any) into the event stream
+6.  if active task is waiting_for_user_reply AND no user_message arrived
+        → re-queue the trigger with a 3-hour delay → return
+7.  _is_complex_task_mode(session)     → _handle_complex_task_workflow
+8.  _is_simple_task_mode(session)      → _handle_simple_task_workflow
+9.  default                            → _handle_conversation_workflow
+```
+
+Steps 7-9 share the same shape: `_select_action` (LLM picks actions; session caching for cache hits) → `_retrieve_and_prepare_actions` → `_execute_actions` → `_finalize_action_execution`. The differences are session state, todo handling, and caching strategy.
+
+### Workflows
+
+**memory** — `_handle_memory_workflow`
+- Trigger source: scheduler `memory-processing` (daily 3am) or startup replay if EVENT_UNPROCESSED.md is non-empty.
+- Behavior: spawns a task that uses the `memory-processor` skill. The task reads EVENT_UNPROCESSED.md, scores events, distills important ones into MEMORY.md, clears the buffer. May also prune MEMORY.md if `max_items` is exceeded.
+- During this task, `event_stream_manager.set_skip_unprocessed_logging(True)` is on, so the task's own events do not loop back into EVENT_UNPROCESSED.md. Reset on `task_end`.
+- Skipped entirely if `is_memory_enabled()` is False.
+- See `## Memory`.
+
+**proactive heartbeat** — `_handle_proactive_heartbeat`
+- Trigger source: scheduler `heartbeat` (cron `0,30 * * * *`).
+- Behavior: `proactive_manager.get_all_due_tasks()` collects due recurring tasks across all frequencies. If none, returns silently. Otherwise creates one `Heartbeat` task: `mode=simple`, `action_sets=[file_operations, proactive, web_research]`, `skill=heartbeat-processor`.
+- Skipped entirely if `is_proactive_enabled()` is False.
+- See `## Proactive`.
+
+**proactive planner** — `_handle_proactive_planner`
+- Trigger source: scheduler `day-planner` (daily 7am), `week-planner` (Sun 5pm), `month-planner` (1st 8am).
+- Behavior: creates a task named `<Day|Week|Month> Planner`, mode=simple, action_sets=[file_operations, proactive], skill=`<scope>-planner`. Task instruction: review recent interactions and update the Goals/Plan/Status section of PROACTIVE.md.
+
+**complex task** — `_handle_complex_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == False`.
+- Full todo state machine; user-approval gate at the end. Session caching enabled for multi-turn efficiency. Parallel action execution supported.
+- See `## Tasks` for the full lifecycle.
+
+**simple task** — `_handle_simple_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == True`.
+- Same select→prepare→execute→finalize flow as complex; no todos; auto-ends. Session caching enabled.
+
+**conversation** — `_handle_conversation_workflow`
+- Active when no task is running for the session.
+- Same flow as simple/complex but uses prefix caching only (no session cache). Supports parallel `task_start` to launch multiple tasks at once.
+- If the executed actions return a `task_id`, the session adopts that task and subsequent triggers route to the task workflow.
+
+### Re-entry and waiting
+
+Calling `wait` or having a task in `waiting_for_user_reply` does not block the loop — it queues a trigger with `fire_at` in the future. When that trigger fires:
+- If the wait was for a user reply and one arrived → process normally.
+- If no user message arrived but the task is still flagged `waiting_for_user_reply` → react re-queues the trigger with a fresh 3-hour delay and returns. The agent silently waits without consuming context.
+
+### Components attached at construction
+
+You do not call these directly, but every action routes through them. Knowing what owns what helps you debug:
+
+```
+LLMInterface           text + vision generation gateway
+ActionLibrary          DB-backed action storage (atomic + divisible)
+ActionManager          action lifecycle
+ActionRouter           LLM-based action selection
+ActionExecutor         sandboxed (ephemeral venv) or internal execution
+TaskManager            task lifecycle, per-task event streams, session storage
+StateManager           session state, current_task_id, current_task
+ContextEngine          builds system + user prompt each turn (KV cache aware)
+MemoryManager          ChromaDB-backed RAG over agent_file_system
+EventStreamManager     appends to EVENT.md / EVENT_UNPROCESSED.md / per-task streams
+MCPClient              external MCP tool servers
+SkillManager           SKILL.md discovery + selection + reload
+Scheduler              cron-driven trigger fires from scheduler_config.json
+ProactiveManager       PROACTIVE.md registry + get_all_due_tasks()
+ExternalCommsManager   platform listeners + senders
+WorkflowLockManager    blocks concurrent memory / proactive runs
+```
+
+### Workflow locks
+
+[agent_core/core/impl/workflow_lock/manager.py](agent_core/core/impl/workflow_lock/manager.py) gates concurrent runs of background workflows. Lock names in use:
+
+```
+"memory_processing"        only one memory-processor task at a time
+"proactive_*"              one proactive workflow per scope at a time
+```
+
+If a trigger fires while its lock is held, the new trigger is dropped silently. The next scheduled fire will pick up the work. This is by design — do not work around it.
+
+### State and context every turn
+
+What the LLM sees on each `_select_action` call:
+- Static system prompt (your role, policy, file-system map, environment).
+- The relevant slice of the event stream (recent actions, results, user messages).
+- Memory pointers retrieved by the ContextEngine for relevance.
+- Current task state if a task is active (instruction, todos, action sets, skills selected).
+- The list of currently available actions (filtered by selected action sets and current mode).
+
+Knowing this shape helps you decide what context to enrich. Need history beyond what's in the stream? Use `memory_search` (`## Memory`) or read TASK_HISTORY.md / CONVERSATION_HISTORY.md directly (`## File System`).
+
+---
+
+## Tasks
+
+Three runtime modes route through this section: **conversation**, **simple**, **complex**. Each has a distinct purpose, action surface, and starting move.
+
+### Conversation mode
+
+Active when **no task is running** for the session. Default state when a user message arrives in a fresh session.
+
+Action surface in conversation mode is intentionally small ([agent_core/core/prompts/action.py](agent_core/core/prompts/action.py)):
+```
+task_start(...)        begin a task — THE way user requests become work
+send_message(...)      reply without starting a task
+ignore                 user input needs no reply (e.g. emoji-only ack)
+```
+
+You CANNOT call file ops, web search, MCP tools, integrations, or skills directly from conversation mode. To unlock them, start a task first.
+
+You MAY emit multiple `task_start` actions in parallel from a single conversation turn. Example: user says "research topic A and topic B" → two parallel `task_start` calls, one per topic.
+
+When to stay in conversation mode:
+- Greeting, small talk, clarifying question.
+- Acknowledging a user message that needs no work.
+- Routing decisions where the user must confirm before any task starts (e.g. "do you want me to delete X?").
+
+When to leave conversation mode (call `task_start`):
+- ANY request that needs file access, web, MCP, skills, integrations, or memory beyond what's in your current context.
+- Even if you "think" you know the answer — if the request is computer-based and could benefit from verification, start a task. Do not refuse a task by claiming a limitation without checking.
+
+### Starting a task: `task_start` vs `schedule_task`
+
+```
+From conversation (no active task)  →  task_start(task_name, task_description, task_mode)
+From inside a task (simple/complex) →  schedule_task(name, instruction, schedule="immediate", mode, ...)
+For later / recurring execution     →  schedule_task(name, instruction, schedule="<expr>", ...)
+```
+
+**`task_start` cannot be called from inside another task.** If you're mid-task and need to spawn a separate one, use `schedule_task` with `schedule="immediate"`. The two actions create equivalent task objects — the difference is the entry point.
+
+`schedule_task` schedule expressions (validated by [app/scheduler/parser.py](app/scheduler/parser.py)):
+```
+"immediate"               run right now (queues an immediate trigger)
+"at 3pm" / "at 3:30pm"    one-time today
+"tomorrow at 9am"         one-time tomorrow
+"in 2 hours" / "in 30 minutes"    one-time relative
+"every day at 7am"        recurring daily
+"every monday at 9am"     recurring weekly
+"every 3 hours"           recurring interval
+"0 7 * * *"               cron (5-field)
+```
+Times must include `am`/`pm`. Freeform like "daily at", "weekly", "every morning", "every weekday" are NOT accepted.
+
+One-time scheduled tasks are auto-removed after firing. Recurring schedules persist in [app/config/scheduler_config.json](app/config/scheduler_config.json).
+
+### Simple mode
+
+Use for work completable in 2-3 actions where no user approval is required at the end.
+
+Pick simple when:
+- Quick lookup (weather, time, exchange rate).
+- Single-answer question (calculation, conversion).
+- Search and summarize where the result is the response.
+- No file the user must review.
+- No irreversible external action (no sends, no payments, no destructive writes).
+
+Flow:
+```
+1. task_start(task_mode="simple", ...)            ← from conversation
+   OR schedule_task(mode="simple", schedule="immediate", ...)  ← from inside a task
+2. (optional) send_message — brief ack
+3. Execute the 1-3 actions
+4. send_message — deliver the result
+5. task_end                                       ← auto-completes, no approval gate
+```
+
+Simple-mode rules:
+- No `task_update_todos`. No phase prefixes. The work is small enough that planning would slow you down.
+- Session caching IS active during simple-mode multi-turn execution (cache hits across the 2-3 turns).
+- If during execution you discover the work is bigger than simple — STOP. End the simple task with the partial result via `send_message` + `task_end`. Then `schedule_task(schedule="immediate", mode="complex")` for the remainder. Do NOT silently chain more actions in simple mode.
+
+### Complex mode
+
+Use for multi-step work, file outputs, irreversible operations, anything the user calls a "project", or anything spanning multiple sessions.
+
+Pick complex when:
+- Plan has more than 3 actions.
+- Output is a file or artifact the user should review and approve.
+- Work touches external state (sends messages, makes purchases, modifies third-party data).
+- Work spans multiple sessions or days (mission-scale — see `## Workspace`).
+
+State machine:
+```
+task_start(task_mode="complex", ...)             ← from conversation
+   OR schedule_task(mode="complex", schedule="immediate", ...)  ← from inside a task
+       │
+       ▼
+send_message                                      ← acknowledge IMMEDIATELY
+       │
+       ▼
+task_update_todos(<full plan, all "pending", phase-prefixed>)
+       │
+       ▼
+loop {
+    mark ONE todo "in_progress"
+    execute relevant actions (parallel within the same todo is fine)
+    mark that todo "completed"
+    if you discover missing info → add a fresh "Collect:" todo, revert
 }
+       │
+       ▼
+send_message(<final result + explicit approval request>)
+       │
+       ▼
+wait for user reply  ← queues a future trigger; you do NOT block, see ## Runtime
+       │
+       ▼
+task_end                                          ← only after explicit approval
 ```
 
-Common patterns:
-- NPX packages: `"command": "npx", "args": ["-y", "@modelcontextprotocol/server-name"]`
-- Python servers: `"command": "uv", "args": ["run", "--directory", "/path/to/server", "main.py"]`
-- HTTP/SSE servers: `"transport": "sse", "url": "http://localhost:3000/mcp"`
-
-### 2. Skill - Install Workflows and Instructions
-Config file: `app/config/skills_config.json`
-Skills directory: `skills/`
-
-When you need specialized workflows or domain knowledge:
-1. Use `read_file` to check `app/config/skills_config.json` for existing skills
-2. Use `web_search` to find skills: search "SKILL.md <domain>" or "<capability> agent skill github"
-3. Use `run_shell` to clone the skill repository into the `skills/` directory:
-   `git clone https://github.com/user/skill-repo skills/skill-name`
-4. Use `stream_edit` to add the skill name to `enabled_skills` array in `app/config/skills_config.json`
-5. The system will automatically detect the change and load the new skill
-
-### 3. App - Configure Integrations
-Config file: `app/config/external_comms_config.json`
-
-When you need to connect to communication platforms:
-1. Use `read_file` to check current config in `app/config/external_comms_config.json`
-2. Use `stream_edit` to update the platform configuration:
-   - Set required credentials (bot_token, api_key, phone_number, etc.)
-   - Set `"enabled": true` to activate
-3. The system will automatically detect the change and start/stop platform connections
-
-Supported platforms:
-- Telegram: bot mode (bot_token) or user mode (api_id, api_hash, phone_number)
-- WhatsApp: web mode (session_id) or API mode (phone_number_id, access_token)
-
-### 4. Model & API Keys - Configure Providers
-Config file: `app/config/settings.json`
-
-When you need different model capabilities or need to set API keys:
-1. Use `read_file` to check current settings in `app/config/settings.json`
-2. If the target model has no API key, you MUST ask the user for one. Without a valid API key, all LLM requests will fail.
-3. Use `stream_edit` to update model configuration and/or API keys:
-```json
+### Todo phase prefixes (mandatory in complex mode)
+
+Every todo must begin with one of these prefixes:
+```
+Acknowledge:   Restate the user's goal in your own words
+Collect:       Gather inputs (read files, search, ask user, list integrations)
+Execute:       Do the work (generate, transform, send, write)
+Verify:        Check the output meets the goal (re-read files, run tests, smoke-test)
+Confirm:       Present the result to the user for approval
+Cleanup:       Remove temp files, restore state, close connections
+```
+
+Rules:
+- Exactly ONE todo `in_progress` at a time. Always.
+- Never skip Verify on todos that produce files or change external state.
+- Never reach Cleanup before Confirm has been signed off by the user.
+- If during Execute you discover missing info, add a new `Collect:` todo and revert. Do not guess.
+- Cleanup is also where you remove `workspace/tmp/{task_id}/` artifacts you do not want to persist (the directory is auto-cleaned anyway, but explicit cleanup catches files saved elsewhere).
+
+### Action sets and skills (locked at task start)
+
+When a task is created via `task_start` or `schedule_task`, action sets and skills are selected automatically by the LLM based on the task description ([app/internal_action_interface.py](app/internal_action_interface.py) `do_create_task`). If the task was started via a skill slash command (e.g. `/pdf`), the pre-selected skill bypasses LLM skill selection but action sets are still LLM-selected and merged with skill-recommended ones.
+
+Once the task starts, the selection is **locked**. Mid-task changes:
+- Action sets: `action_set_management` action can add/remove sets.
+- Skills: cannot be swapped mid-task. End the task and start a new one if you need a different skill.
+
+### Output destinations
+
+- Files the user should keep across sessions → `agent_file_system/workspace/`
+- Drafts, sketches, intermediate state → `agent_file_system/workspace/tmp/{task_id}/` (auto-cleaned on `task_end` and on agent start)
+- Mission-scale, multi-task initiatives → `agent_file_system/workspace/missions/<mission_name>/INDEX.md`
+
+See `## Workspace` for the mission template and scan-on-start protocol.
+
+### Common task-mode mistakes to avoid
+
+- Starting in **simple**, work grows mid-task → do NOT silently chain more actions. End simple, schedule complex.
+- Calling `task_start` **from inside a task** → it doesn't work that way. Use `schedule_task` instead.
+- Using `schedule_task("immediate")` **from conversation** → use `task_start`. Conversation is built around it; using `schedule_task` from conversation creates an extra trigger hop.
+- Calling `task_end` **without a final `send_message`** → simple tasks must deliver the result; complex tasks must summarize and request approval. Never end silently.
+- Marking todos `completed` **before the actions ran** → mark `in_progress`, run, then mark `completed`.
+- Adding planning todos like `Acknowledge: Plan the work` to simple tasks → simple tasks do not use todos at all.
+
+---
+
+## Communication Rules
+
+The user only sees what you send via `send_message` (or `send_message_with_attachment`). Everything else — actions, errors, internal reasoning — is invisible to them.
+
+Cadence:
+- **Acknowledge immediately** after `task_start`. One sentence is enough. Don't wait for the first action to complete.
+- **Update on milestones**, not on every action. A milestone is: phase transition (Collect → Execute), significant finding, blocker, request for input.
+- **Stay silent during tight Verify loops.** If you're re-reading a file three times to check formatting, do not narrate each read.
+- **Final message before `task_end`** must summarize what was done, list any artifacts (with paths), and explicitly request approval.
+
+Channel choice:
+- Default: in-context chat.
+- If the user has a `Preferred Messaging Platform` set in `USER.md` and the task is asynchronous (proactive task, scheduled completion), prefer that platform.
+- Use `send_message_with_attachment` when sending generated files; pass the workspace path.
+
+What NOT to send:
+- Internal reasoning ("I'm now thinking about...").
+- Tool-call narration ("Let me run grep_files...").
+- Repeated acknowledgements after the first.
+- Status pings during fast operations.
+
+Hard rules:
+- Never end a complex task without explicit approval.
+- Never end any task silently.
+- Never claim success when an action failed — see `## Errors`.
+
+---
+
+## Errors
+
+You operate inside a harness with multiple safety layers. Some failures are handled automatically; others require you to recover deliberately. Knowing which is which is the difference between a productive recovery and an infinite loop.
+
+### Action result schema (read this first)
+
+EVERY action — built-in, MCP-routed, or skill-spawned — returns a dict with at minimum:
+
+```
 {
-  "model": {
-    "llm_provider": "anthropic",
-    "vlm_provider": "anthropic",
-    "llm_model": "claude-sonnet-4-20250514",
-    "vlm_model": "claude-sonnet-4-20250514"
-  },
-  "api_keys": {
-    "openai": "sk-...",
-    "anthropic": "sk-ant-...",
-    "google": "...",
-    "byteplus": "..."
-  }
+  "status": "success" | "error",
+  "message": "<human-readable detail>",     # present on error, often present on success
+  ... action-specific output fields ...
 }
 ```
-4. The system will automatically detect the change and update settings (model changes take effect in new tasks)
 
-Available providers: openai, anthropic, gemini, byteplus, remote (Ollama)
+Before you treat an action's output as a result you can act on, **check `status`**. If `status == "error"`, the `message` field tells you what went wrong. Failing to check `status` and proceeding as if everything worked is the most common avoidable failure mode in this harness.
+
+### Error event kinds in the event stream
+
+The event stream ([agent_core/core/impl/event_stream/manager.py](agent_core/core/impl/event_stream/manager.py)) records errors in distinct event kinds. You will see these when reviewing your own past steps:
+
+```
+"error"          react-level errors. LLM failures, exceptions in workflow handlers.
+                 Display message comes from classify_llm_error() (see below).
+"action_error"   actions DROPPED before execution: parallel-constraint violations,
+                 missing actions, invalid decisions.
+                 (Distinct from an action that ran and returned status=error.)
+"warning"        soft warnings that you must heed:
+                 - Action limit at 80% / 100%
+                 - Token limit at 80% / 100%
+                 - Other harness alerts
+"internal"       limit-choice messages, system-side info.
+```
+
+When you see an `"error"` or `"action_error"` event in the stream, it has already been logged. You do NOT need to log it again. You DO need to react to it.
+
+### Harness-level safety nets (do not duplicate)
+
+The harness already handles certain failures so you do not have to. Recognizing them prevents you from stepping on the harness.
+
+**Per-action timeout** ([agent_core/core/impl/action/executor.py](agent_core/core/impl/action/executor.py))
+- Default `DEFAULT_ACTION_TIMEOUT = 6000` seconds (100 min). Individual actions may declare shorter timeouts.
+- On timeout, the action returns:
+  ```
+  {"status": "error", "message": "Execution timed out after Ns while running <internal|sandboxed> action."}
+  ```
+- Recovery: the timeout is final for that invocation. Either retry with smaller scope (fewer rows, narrower regex, smaller batch) or split the work into multiple actions.
+
+**LLM consecutive-failure circuit breaker** ([agent_core/core/impl/llm/errors.py](agent_core/core/impl/llm/errors.py), [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py))
+- After repeated consecutive LLM failures (auth, network, etc.), the harness raises `LLMConsecutiveFailureError`.
+- `_handle_react_error` walks the exception chain (`__cause__`/`__context__`) to detect this and **automatically cancels the task** via `task_manager.mark_task_cancel(...)`. The agent's last instruction is cached in `_llm_retry_instructions[session_id]` for retry-after-fix.
+- A `LLM_FATAL_ERROR` UI event is emitted so the user sees a clear failure dialog.
+- **Implication:** if you see `MSG_CONSECUTIVE_FAILURE` ("LLM calls have failed N consecutive times. Task aborted to prevent infinite retries."), the task is already gone. Do NOT try to re-create it. The user must check their LLM configuration.
+
+**Action limit (`max_actions_per_task`, minimum 5)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Tracked in `STATE.get_agent_property("action_count")` against `max_actions_per_task`.
+- At **80%** the harness logs a `"warning"` event:
+  > "Action limit nearing: 80% of the maximum actions (N actions) has been used. Consider wrapping up the task or informing the user that the task may be too complex. If necessary, mark the task as aborted to prevent premature termination."
+  - Your response: **wrap up**. Send the best result you have, or ask the user whether to abort. Do NOT ignore.
+- At **100%** the harness logs a `"warning"`, sends a Continue/Abort chat message to the user, and PAUSES the task. `_check_agent_limits` returns False; the next trigger does not get scheduled. The task resumes only when the user picks Continue (limits reset) or Abort.
+
+**Token limit (`max_tokens_per_task`, minimum 100000)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Same 80% warning / 100% pause pattern as actions, but for cumulative token usage.
+- 80% warning text is identical except "tokens" instead of "actions".
+- 100% triggers the same Continue/Abort gate.
+- Your response at 80%: same as action warning — wrap up or summarize aggressively.
+
+**Parallel constraint violations**
+- The router may drop an action before it runs and surface a `"action_error"` event with `_error` describing the constraint (e.g., "ignore must run alone", "cannot run multiple send_message in parallel").
+- The action is not executed; subsequent actions in the same batch may still run.
+- Recovery: re-issue the action sequentially in the next turn, not in parallel.
+
+### LLM error classes (from `classify_llm_error`)
+
+When an LLM call fails non-fatally, `classify_llm_error()` returns one of these messages. Knowing the class tells you whether retrying makes sense and what to tell the user:
+
+```
+MSG_AUTH         (HTTP 401/403)   "Unable to connect to AI service. Check your API key in Settings."
+                                  → DO NOT retry. Tell user to set/fix API key. See ## Models.
+MSG_MODEL        (HTTP 404)       "The selected AI model is not available."
+                                  → DO NOT retry. Tell user model name is wrong/unavailable.
+MSG_CONFIG       (HTTP 400)       "AI service configuration error. The selected model may not support required features."
+                                  → DO NOT retry. May indicate a feature flag (vision, tool use) not supported by chosen model.
+MSG_RATE_LIMIT   (HTTP 429)       "AI service is rate-limited. Please wait a moment and try again."
+                                  → Retryable after delay. Consider enabling slow_mode in settings.
+MSG_SERVICE      (HTTP 5xx)       "AI service is temporarily unavailable. Please try again later."
+                                  → Retryable. Often transient.
+MSG_CONNECTION   (timeout, ConnectionError)  "Unable to reach AI service. Check your internet."
+                                  → Retryable if connectivity recovers.
+MSG_GENERIC      (unmatched)      "An error occurred with the AI service."
+                                  → Investigate before retrying.
+```
+
+These come back as user-friendly strings to display; the harness wraps them in `"error"` events. You see them via the event stream and `display_message`.
+
+### Failure taxonomy and recovery decision
+
+There are four failure types. Identify which one you are in, then follow the matching recovery.
+
+**TRANSIENT**
+- Symptoms: rate limit, transient 5xx, connection error, file lock, sandbox process hiccup.
+- Action: wait briefly, retry ONCE with the same params.
+- Budget: 1 retry per action invocation. No second retry on the same params.
+
+**APPROACH**
+- Symptoms: action returned `status=error` with a "bad params" / "not found" / "invalid format" message. Semantic mismatch (you grepped the wrong file, ran the wrong action).
+- Action: change the approach. Different action, different params, different plan. Do NOT retry the same call unchanged.
+- Examples:
+  - `read_file` on a non-existent path → `find_files` first.
+  - `schedule_task` with `"daily at 9am"` rejected → use `"every day at 9am"` (the validated format).
+
+**IMPOSSIBLE**
+- Symptoms: missing access (no API key, no integration), hardware action needed (physical printer), policy violation, user data the agent cannot access.
+- Action: stop. `send_message` explaining what was tried and why it cannot work. Offer alternatives if any. For complex tasks, mark the task aborted.
+- Examples:
+  - `/linkedin login` required → ask user to authenticate.
+  - "send a fax" → state limitation, suggest email.
+
+**LOOP**
+- Symptoms: same action + same params + same error TWICE.
+- Action: stop immediately. Escalate to user with a specific question. Do NOT try a third time.
+- Why: loops burn action/token budget and produce no progress. The harness's `max_actions_per_task` and `LLMConsecutiveFailureError` limits are backstops, not your primary safety.
+
+### Recovery patterns by error source
+
+**File / shell / Python action returns `status=error`**
+- Read the `message` field. It often points at the fix (file not found, permission, syntax error, missing dep).
+- If the message says missing dependency for `run_python` / `run_shell`, install it via `pip install`/`npm install` in a follow-up `run_shell` call (auto-installed in sandboxed mode for declared `requirements`, but ad-hoc imports require explicit install).
+- If it says path not found, `find_files` or `list_folder` to locate before retry.
+
+**Web / fetch action returns error**
+- HTTP 4xx → URL or auth wrong. Don't retry the same URL.
+- HTTP 5xx or timeout → transient. One retry, then fall back (different URL, cached source, or report unavailability).
+- Empty result on `web_search` → broaden query or try a different search term. Do NOT keep retrying the same query.
+
+**Schedule / proactive action returns error**
+- Schedule expression rejected by parser → see `## Tasks` for the validated format list. Re-issue with a supported expression.
+- Recurring task creation fails → check PROACTIVE.md for syntax errors near your edit; the file's HTML markers (`PROACTIVE_TASKS_START`/`END`) must remain intact.
+
+**MCP tool returns error**
+- Server-side error in the MCP tool → check EVENT.md for stderr from the MCP server process. Often missing API key in the server's `env` block.
+- Tool not found → server may be disabled in `mcp_config.json` or the `action_set_name` not loaded. See `## MCP`.
+
+**Action limit / token limit warning at 80%**
+- Wrap up. Send the partial result and ask the user whether to continue.
+- If the work genuinely needs more budget, ask the user explicitly — they can pick Continue at the 100% gate and the limits reset.
+- Marking the task as aborted (`task_end` with status=aborted/failed) is preferable to silently exceeding the limit and pausing the task.
+
+**Action limit / token limit reached (100%)**
+- The task is paused; you don't get a next trigger until the user chooses Continue or Abort.
+- Do NOT attempt to schedule anything or send messages — the harness has already sent the user a Continue/Abort dialog.
+- When the user picks Continue, your next trigger arrives with limits reset.
+
+**LLM call failed (non-fatal)**
+- The harness retries internally up to its consecutive-failure threshold.
+- If you see a `"error"` event with one of the `MSG_*` strings, treat it according to the class table above.
+- If it escalates to `LLMConsecutiveFailureError` (`MSG_CONSECUTIVE_FAILURE`), the task is already cancelled. Do not try to recreate it.
+
+### Self-troubleshooting via logs
+
+When the action's `status=error` message does not tell you enough to recover, drop down to the runtime logs. The agent harness writes everything it does to disk, and you can read it.
+
+**Three log surfaces. Know which to use for what.**
+
+```
+EVENT.md                       agent_file_system/EVENT.md
+                               your perspective: events you produced/observed
+                               (action_start, action_end, send_message, error,
+                               warning, action_error, internal). Already on disk
+                               and indexed by memory_search.
+
+logs/<timestamp>.log           project_root/logs/
+                               runtime perspective: harness internals, every
+                               subsystem's INFO/WARN/ERROR log line. Loguru
+                               format. Rotates at 50 MB, kept 14 days.
+                               This is where stderr from sandboxed actions,
+                               MCP server output, and Python tracebacks land.
+
+diagnostic/logs/actions/       diagnostic/logs/actions/<ts>_<slug>.log.json
+                               per-action diagnostic dump (when run via the
+                               diagnostic harness). Contains full input/output
+                               for individual actions. See diagnostic/README.md.
+```
+
+**Picking the right surface:**
+- "What did I do, and what did the harness say back?" → EVENT.md.
+- "Why did this action / MCP / hot-reload actually fail?" → `logs/<timestamp>.log`.
+- "I want to replay one specific action's full input/output" → `diagnostic/logs/actions/`.
+
+**Log line format (loguru):**
+```
+2026-05-03 16:00:12.066 | INFO     | agent_core.core.database_interface:__init__:60 - Action registry loaded. 195 actions...
+^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+timestamp                  level      module:function:line                          message
+```
+- Levels: `DEBUG` < `INFO` < `WARNING` < `ERROR`. Default file threshold is INFO; harness emits a lot at INFO, so most context is captured.
+- The `module:function:line` segment tells you exactly where in the codebase the message came from. You can `read_file <module path>` and jump to the line for full context.
+
+**Subsystem tags you will see in messages.** Most subsystems prefix their log lines with a bracketed tag — grep for these:
+
+```
+[REACT]            react loop main flow                       app/agent_base.py
+[REACT ERROR]      react-level exceptions caught              app/agent_base.py:_handle_react_error
+[ACTION]           action preparation and execution           app/agent_base.py:_execute_actions
+[TASK]             task lifecycle (create, update, end)       agent_core/core/impl/task/manager.py
+[MEMORY]           memory indexing and processing             agent_core/core/impl/memory/manager.py
+[MCP]              MCP server init, connect, tool calls       agent_core/core/impl/mcp/client.py
+[SETTINGS]         settings load and updates                  agent_core/core/impl/settings/manager.py
+[CONFIG_WATCHER]   hot-reload events                          agent_core/core/impl/config/watcher.py
+[LIMIT]            action/token limit choice messages         app/agent_base.py
+[SESSION]          session cache lifecycle                    agent_core/core/impl/llm/interface.py
+[STATE]            state-debug snapshots                      app/agent_base.py
+[ONBOARDING]       onboarding state                           agent_core/core/impl/onboarding/manager.py
+[PROACTIVE]        proactive workflow                         app/proactive/manager.py
+[RESTORE]          startup task restoration                   app/agent_base.py:_restore_sessions
+[AGENT]            agent init, mode toggles                   app/agent_base.py:__init__
+[LLM FACTORY]      LLM provider construction                  agent_core/core/impl/llm/interface.py
+```
+
+**Self-troubleshooting workflow.** When an action returns an error you cannot decode from `message` alone:
+
+```
+1. Identify the latest log file:
+     list_folder logs/                        ← logs are timestamped, latest is freshest
+2. Find the time window of the failure:
+     - From EVENT.md, note the timestamp of the failing event.
+     - That same timestamp will exist in logs/<latest>.log (within seconds).
+3. Grep around that time + the relevant subsystem tag:
+     grep_files "[MCP]"   logs/<latest>.log -A 5 -B 1   ← MCP server failure?
+     grep_files "[ACTION]" logs/<latest>.log -A 5 -B 1   ← action execution issue?
+     grep_files "ERROR"    logs/<latest>.log -B 2 -A 10  ← any error-level line + context
+4. If a Python traceback is present, read upward from the traceback to the
+   most recent INFO line in the same subsystem — that tells you the last
+   successful step before the failure.
+5. The "module:function:line" field on the failing log line points at the code
+   path. read_file <module path> with offset = line - 30 to inspect.
+6. Decide:
+     - The error is in your action params       → ## Errors / APPROACH
+     - The error is in a subsystem (MCP server crash, settings parse error,
+       hot-reload exception)                   → ## MCP / ## Configs / ## Hot Reload
+     - The error is in the LLM call             → see classify_llm_error classes above
+     - The error is environmental (no API key,
+       missing dep, port in use)               → tell the user, do not retry blindly
+```
+
+**Concrete grep recipes:**
+
+```
+# Did an MCP server crash on startup or fail to connect?
+grep_files "[MCP]" logs/<latest>.log -A 3
+# → look for "Failed to connect", "subprocess exited", non-zero return codes.
+
+# Did the config watcher fail to apply a hot reload?
+grep_files "[CONFIG_WATCHER]" logs/<latest>.log -A 3
+
+# Did settings.json fail to parse?
+grep_files "[SETTINGS]" logs/<latest>.log -A 3
+
+# Did an action time out, and which one?
+grep_files "Execution timed out" logs/<latest>.log -B 5
+
+# Did the LLM hit consecutive failures?
+grep_files "LLMConsecutiveFailureError\|MSG_CONSECUTIVE_FAILURE" logs/<latest>.log -A 5
+
+# Did a sandboxed action subprocess produce stderr?
+grep_files "venv\|requirements\|subprocess" logs/<latest>.log -A 3
+
+# What did the agent's _check_agent_limits last log?
+grep_files "[LIMIT]" logs/<latest>.log -A 2
+
+# When did the last task end, and how?
+grep_files "[TASK].*ended\|task_end\|mark_task_cancel" logs/<latest>.log -A 3
+
+# Find the last 100 ERROR-level lines across the whole log:
+grep_files "| ERROR " logs/<latest>.log -A 5
+```
+
+**Acting on what you find.** A log line is data, not a fix. The decision rules:
+
+```
+If the log shows                               then
+─────────────────────────────────────────────  ──────────────────────────────────────
+[MCP] subprocess exited with code N            MCP server crashed. Inspect its env in
+                                               mcp_config.json. Likely missing API
+                                               key or wrong command path. See ## MCP.
+
+[SETTINGS] JSONDecodeError                     settings.json is malformed. Read the
+                                               file, find the syntax error around the
+                                               reported line, fix via stream_edit.
+
+[CONFIG_WATCHER] reload failed                 the change was not picked up. Save
+                                               again, or check the file is tracked in
+                                               watcher.register() (see ## Hot Reload).
+
+[REACT ERROR] LLMConsecutiveFailureError       harness already cancelled the task.
+                                               Tell user to fix LLM config. Do NOT
+                                               retry. See ## Models.
+
+[LIMIT] ... 100% ... Waiting for user choice   task is paused. Do not issue actions
+                                               until next trigger. See ## Errors above.
+
+ModuleNotFoundError in run_python output       the script needs a dependency. Install
+                                               via run_shell "pip install <pkg>" or
+                                               declare in action requirements.
+
+PermissionError / OSError on file write        the path is wrong, locked, or outside
+                                               the allowed scope. Verify with
+                                               list_folder; prefer workspace/ for
+                                               outputs.
+
+Long gaps between INFO lines (no activity)     the loop may be waiting for a trigger
+                                               (waiting_for_user_reply, scheduled
+                                               fire). Check the next trigger fire_at
+                                               in ProactiveManager / Scheduler.
+```
+
+**When logs are the only honest source of truth.** Some failures do not surface as `status=error` in the action result — they manifest as the action *seeming to work* but the side effect not happening (e.g., `run_shell` returns 0 but a script printed "ok" while silently catching an exception; an MCP tool returns success but logged a warning that the operation was a no-op). When you suspect a silent failure, grep the logs for the timestamp of your action and look for `WARNING` or unexpected `ERROR` lines around it.
+
+**Rotation and freshness.** Log files rotate at 50 MB and old files are kept for 14 days. The latest file by mtime is the one with current activity. If your investigation needs older history (e.g., a crash from yesterday), `list_folder logs/` and pick by timestamp.
+
+**Do not ask the user for log content you can read yourself.** The user does not have a better view than you do. If they ask "what's the error?", read the log, summarize, and explain. They are not your support layer — you are theirs.
+
+### Surfacing failures to the user
+
+Mid-task (recoverable):
+- `send_message` with: what failed (one sentence), what you tried (1-3 bullets), what you'll try next (one sentence).
+- Do not surface every transient retry. The user does not need to know about a single rate-limit retry that succeeded.
+
+Terminal (cannot recover):
+- For complex tasks: `send_message` with the failure summary + any salvageable partial result, then `task_end` with a failed-status summary.
+- For simple tasks: `send_message` with the failure, then `task_end`.
+- Mark task aborted via `task_manager.mark_task_cancel(...)` semantics ONLY through the proper action paths (don't try to invoke internals directly).
+- Never fabricate success. If you couldn't read the file, do not paraphrase what you "would have" found.
+
+### When you're blocked but not failed
+
+You're blocked when you don't know what to do next AND retrying won't help. The recovery is information, not action.
+
+```
+1. State the blocker plainly: "I can't proceed because <X>."
+2. List what you tried: "- Tried <A>: <result>. - Tried <B>: <result>."
+3. Ask ONE specific question — not "what should I do".
+   Good:  "Should I use the Slack bot token from settings.oauth.slack, or do you want me to reuse the existing /slack login session?"
+   Bad:   "What do you want me to do?"
+```
+
+### Common error-handling anti-patterns
+
+- **Treating action output as success without checking `status`.** The #1 source of silent failures. Always read the `status` field before using output.
+- **Retrying the same action with the same params** after `status=error` and no change. The error will repeat. Either change a parameter, change the action, or stop.
+- **Ignoring `"warning"` events** about action/token limits. The harness will pause your task soon — get ahead of it. At 80%, wrap up or send the partial result.
+- **Continuing to issue actions while limit-paused (100%).** They will not fire. The user is being shown a Continue/Abort dialog. Wait for the next trigger.
+- **Trying to retry after `LLMConsecutiveFailureError`.** The task is already cancelled by `_handle_react_error`. Do NOT recreate it. Tell the user the LLM configuration needs attention.
+- **Catching exceptions in `run_python` / `run_shell` and printing "ok".** The harness sees `status=success` if your script swallows the error. Always propagate non-zero exit codes / raise on failure.
+- **Fabricating success messages on failure.** Forbidden. If you couldn't read the file or call the API, do not paraphrase what you "would have" produced.
+- **Asking open-ended "what should I do" questions.** Always one specific question with an implied default ("Use the bot token from settings.oauth.slack, or reuse the existing /slack login session?").
+- **Self-detected logical loops.** The consecutive-failure breaker only catches LLM-call failures. If you keep choosing slightly different params for the same action and getting the same business-logic error (e.g., "user not found" three times with three different IDs you guessed), that is a logical loop. Stop and ask the user.
+
+### What the harness does NOT do for you
+
+- It does NOT change your approach when an action fails. You must.
+- It does NOT pick a different action when one returns `status=error`. You must.
+- It does NOT detect a logical loop you've created (same action with slightly different params, same error). The consecutive-failure breaker only catches LLM-call failures, not action-result failures. You must detect logical loops.
+- It does NOT verify that an action's `status=success` result actually achieved your goal. Verify (re-read the file you wrote, re-query the data you updated). See `## Tasks` Verify phase.
+
+---
+
+## Files
+
+### read_file
+- Returns `cat -n` formatted lines plus a `has_more` flag.
+- Default limit is 2000 lines. Use `offset` and `limit` for targeted reads.
+- For files larger than 500 lines: read the head first to learn structure, then `grep_files` for the section you need, then `read_file` with the right offset and limit.
+- Full input schema: [app/data/action/read_file.py](app/data/action/read_file.py).
+
+### grep_files
+Three output modes:
+- `files_with_matches`: returns file paths only. Use for discovery ("which files contain X").
+- `content`: returns matching lines with line numbers. Use for investigation.
+- `count`: returns match counts per file. Use for frequency checks.
+
+Supported parameters: `glob`, `file_type`, `before_context` / `after_context`, `case_insensitive`, `multiline`.
+
+Full input schema: [app/data/action/grep_files.py](app/data/action/grep_files.py).
+
+### stream_read + stream_edit
+- Use as a pair when modifying an existing file.
+- `stream_read` returns the exact bytes.
+- `stream_edit` applies a precise diff.
+- Preferred over `write_file` for edits. Preserves unrelated content and avoids whole-file overwrites.
+
+### write_file
+Use only when:
+- Creating a brand new file, OR
+- Doing a deliberate full rewrite of a small file.
+
+Never use `write_file` to patch an existing large file. Use `stream_edit`.
+
+### find_files vs list_folder
+- `list_folder`: top-level listing of a single directory.
+- `find_files`: recursive name pattern search across a tree.
+
+### convert_to_markdown vs read_pdf
+- `read_pdf`: direct PDF reading with page support.
+- `convert_to_markdown`: for office formats (docx, xlsx, pptx) you intend to grep afterwards.
+
+### Anti-patterns
+- Repeated full reads of large files. Use `grep_files` plus offset reads instead.
+- Chaining four `read_file` calls when one `grep_files` would answer the question.
+- Reading binary files as text. Use the dedicated action (`read_pdf`, `describe_image`, `understand_video`, etc.).
+
+---
+
+## File System
+
+Your persistent file system is `agent_file_system/`. Every file has a defined writer, reader, format, and update rule. Files marked `DO NOT EDIT` are managed by harness subsystems. Touching them creates inconsistency you cannot recover from.
+
+```
+agent_file_system/
+├── AGENT.md                  Operational manual (this file)
+├── USER.md                   User profile
+├── SOUL.md                   Personality (injected to system prompt)
+├── FORMAT.md                 Document / design standards
+├── MEMORY.md                 Distilled facts                     DO NOT EDIT
+├── EVENT.md                  Full event log                      DO NOT EDIT
+├── EVENT_UNPROCESSED.md      Memory-pipeline staging buffer      DO NOT EDIT
+├── CONVERSATION_HISTORY.md   Rolling dialogue log                DO NOT EDIT
+├── TASK_HISTORY.md           Task summaries                      DO NOT EDIT
+├── PROACTIVE.md              Recurring tasks + Goals/Plan/Status
+├── GLOBAL_LIVING_UI.md       Global Living UI design rules
+├── MISSION_INDEX_TEMPLATE.md Template for mission INDEX.md files
+└── workspace/                Sandbox for task outputs (see ## Workspace)
+```
+
+### Indexed for memory_search
+
+The MemoryManager indexes a fixed set of files for semantic retrieval ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py), constant `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Editing any of these triggers re-indexing via [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py). Other files in `agent_file_system/` are NOT indexed. To find content in non-indexed files, use `grep_files` directly.
+
+### AGENT.md
+- Purpose: operational manual for you.
+- Write access: user (manually); you (only for operational improvements you have learned, see `## Self-Edit`).
+- Read pattern: `read_file` / `grep_files` on demand. Always grep by `## <Topic>` header.
+- Format: structured markdown. Stable `## <Topic>` headers. HTML comment markers (`<!-- name -->` ... `<!-- /name -->`) around schema and command blocks.
+- Update rule: bump `version:` in front matter on material changes. Sync to `app/data/agent_file_system_template/AGENT.md` when the change should ship to new installs.
+
+### USER.md
+- Purpose: persona and preferences of the user. Read at the start of any user-facing task.
+- Write access: the agent (after confirming with the user); the onboarding wizard.
+- Read pattern: at session start, when personalizing responses, when picking communication channel.
+- Format: plain markdown sections. Standard sections: `## Identity`, `## Communication Preferences`, `## Agent Interaction`, `## Life Goals`, `## Personality`.
+- Update rule: confirm the preference is durable before writing. One-off requests do not belong here.
+
+### SOUL.md
+- Purpose: personality, tone, behavior. Injected directly into the system prompt every turn.
+- Write access: user (primarily); you only on explicit user request.
+- Read pattern: the system reads on every turn. You do NOT need to `read_file` it during normal operation.
+- Caution: edits affect every interaction immediately on next turn. Confirm with user before saving.
+
+### FORMAT.md
+- Purpose: design and formatting standards for documents you generate.
+- Write access: user (preferences); you when the user supplies a new rule (with confirmation).
+- Read pattern: `grep_files "## <filetype>" agent_file_system/FORMAT.md` before generating any document. See `## Documents`.
+- Sections: `## global` (universal rules), `## pptx`, `## docx`, `## xlsx`, `## pdf`. Type-specific sections override `## global`.
+
+### MEMORY.md
+- Purpose: distilled long-term memory. Survives across sessions.
+- Write access: ONLY the memory processor (daily 3am job, plus startup replay if EVENT_UNPROCESSED.md is non-empty).
+- Hard rule: you MUST NOT edit MEMORY.md directly. Use the memory pipeline. See `## Memory`.
+- Read pattern: `memory_search` action (RAG, returns relevance-ranked pointers). Do NOT grep MEMORY.md directly for retrieval.
+- Format: `[YYYY-MM-DD HH:MM:SS] [type] content` — one fact per line.
+- Types: `capability`, `project`, `workspace`, `focus`, `preference`, `analysis`, `user_complaint`, `system_warning`, `system_limit`.
+
+### EVENT.md
+- Purpose: complete chronological event log. Append-only.
+- Write access: EventStreamManager. Hard rule: DO NOT edit.
+- Read pattern: `read_file` / `grep_files` for self-troubleshooting. See `## Errors` for log workflow.
+- Format: `[YYYY/MM/DD HH:MM:SS] [event_type]: payload`. Multi-line payloads continue on subsequent lines.
+- Auto-rotated when size threshold is exceeded.
+
+### EVENT_UNPROCESSED.md
+- Purpose: staging buffer for events awaiting memory distillation.
+- Write access: EventStreamManager (filtered subset of EVENT.md events). Hard rule: DO NOT edit.
+- Read pattern: the memory processor reads it daily 3am. See `## Memory`.
+- Cleared: after each successful memory-processing run.
+- Filter: events of kind `action_start`, `action_end`, `todos`, `error`, `waiting_for_user` are NOT staged. The pipeline focuses on user-facing dialogue and important state changes.
+- Skip flag: during memory-processing tasks, `set_skip_unprocessed_logging(True)` prevents the task's own events from looping back. Reset automatically on `task_end`.
+
+### CONVERSATION_HISTORY.md
+- Purpose: rolling dialogue record across all sessions.
+- Write access: EventStreamManager (on every user/agent message). Hard rule: DO NOT edit.
+- Read pattern: when restoring context for a returning user or reviewing what was said.
+- Format: `[YYYY/MM/DD HH:MM:SS] [sender]: message`. Sender is `user` or `agent`. Multi-line messages continue under one header.
+- Lifespan: permanent. Never auto-cleared.
+
+### TASK_HISTORY.md
+- Purpose: summary of every completed (or cancelled) task.
+- Write access: appended on `task_end`. Hard rule: DO NOT edit.
+- Read pattern: when checking past outcomes for a similar task.
+- Format: one markdown section per task:
+  ```
+  ### Task: <task name>
+  - **Task ID:** <id>
+  - **Status:** completed | cancelled | failed
+  - **Created:** <ISO timestamp>
+  - **Ended:** <ISO timestamp>
+  - **Summary:** <one-paragraph outcome>
+  - **Instruction:** <original task instruction>
+  - **Skills:** <skill names used>
+  - **Action Sets:** <action set names used>
+  ```
+
+### PROACTIVE.md
+- Purpose: recurring proactive task definitions plus the planner-maintained Goals / Plan / Status section.
+- Write access: `recurring_add` / `recurring_update_task` / `recurring_remove` actions; planners (day, week, month).
+- Read pattern: every heartbeat (every 30 min); planners on their schedules; you when the user asks about scheduled work. See `## Proactive`.
+- Format: YAML blocks between `<!-- PROACTIVE_TASKS_START -->` and `<!-- PROACTIVE_TASKS_END -->` markers, followed by a Goals / Plan / Status section.
+- Authority: PROACTIVE.md is the source of truth for the Decision Rubric, Permission Tiers, and recurring-task YAML schema. Do NOT duplicate that content elsewhere.
+
+### GLOBAL_LIVING_UI.md
+- Purpose: global design rules applied to every Living UI project.
+- Write access: user (primarily). You only when the user supplies a new universal rule with confirmation.
+- Read pattern: before creating any Living UI project. See `## Living UI`.
+- Sections: Design Preferences (colors, theme, font, border radius, spacing), Always Enforced rules, Optional rules, Custom rules.
+
+### MISSION_INDEX_TEMPLATE.md
+- Purpose: template for `workspace/missions/<name>/INDEX.md`. See `## Workspace`.
+- Write access: static template. DO NOT edit.
+- Read pattern: when starting a mission, copy this template into the mission directory and fill it in.
+- Fields: Goal, Status, Key Findings, What's Been Tried, Next Steps, Resources & References, Constraints & Notes.
+
+### Living UI projects (workspace/living_ui/)
+
+Living UI projects live at `agent_file_system/workspace/living_ui/<project_name>_<hash>/`. Internal structure varies project to project depending on what the user asked for (different stacks, frameworks, file layouts). Do NOT assume any particular structure beyond the three required files below. To see what's actually in a specific project, `list_folder` it. For lifecycle (create, modify, restart, inspect), use `living_ui_actions`. See `## Living UI`.
+
+Required files (every project has these):
+
+```
+workspace/living_ui/<name>_<hash>/
+├── LIVING_UI.md          Per-project doc: purpose, decisions, project-specific rules
+├── config/
+│   └── manifest.json     Project metadata: name, hash, ports, capabilities
+└── logs/                 Project logs (timestamped). Format and filenames vary per project.
+```
+
+- `LIVING_UI.md`: read this first when working on an existing project. Records purpose, design decisions, and any project-specific overrides of `GLOBAL_LIVING_UI.md`.
+- `config/manifest.json`: read by the runtime to identify the project and its assigned ports. Do not rename a project directory by hand. Re-register via `living_ui_actions` instead.
+- `logs/`: where the project's runtime, build, and console output land. First place to grep when a project misbehaves.
+
+Everything else (backend, frontend, build output, dependency caches, databases) is project-specific. To learn what a fresh-from-template project would contain (one possible shape, not the only one), see [app/data/living_ui_template/](app/data/living_ui_template/).
+
+### Files outside agent_file_system/
+
+Some persistent state the agent interacts with lives outside this directory:
+
+```
+app/config/settings.json              model, API keys, OAuth, cache              (## Configs)
+app/config/mcp_config.json            MCP server registry                         (## MCP)
+app/config/skills_config.json         enabled / disabled skills                   (## Skills)
+app/config/external_comms_config.json platform listener configs                   (## Integrations)
+app/config/scheduler_config.json      cron schedules                              (## Proactive)
+app/config/onboarding_config.json     first-run state                             (## Onboarding)
+skills/<name>/SKILL.md                installed skills                            (## Skills)
+.credentials/<platform>.json          OAuth tokens, bot tokens, API keys
+                                      DO NOT print contents to chat or logs
+logs/<timestamp>.log                  runtime logs                                (## Errors)
+chroma_db_memory/                     ChromaDB index for memory_search
+                                      DO NOT edit
+```
+
+---
 
-### 5. Memory - Learn and Remember
-When you learn something useful (user preferences, project context, solutions to problems):
-- Use `memory_search` action to check if relevant memory already exists
-- Store important learnings in MEMORY.md via memory processing actions
-- Use `read_file` to read USER.md and AGENT.md to understand context before tasks
-- Use `stream_edit` to update USER.md with user preferences you discover
-- Use `stream_edit` to update AGENT.md with operational improvements
+## Workspace
+
+`agent_file_system/workspace/` is your sandbox for task output. Three subdirectories with distinct lifecycles:
+
+```
+agent_file_system/workspace/
+├── <files at root>           Persistent task outputs the user should keep across sessions
+├── tmp/
+│   └── {task_id}/            Per-task scratch directory. Auto-cleaned.
+├── missions/
+│   └── <mission_name>/       Multi-task initiative. Persists indefinitely.
+│       ├── INDEX.md          Required (template at MISSION_INDEX_TEMPLATE.md)
+│       └── <mission files>
+└── living_ui/
+    └── <name>_<hash>/        Living UI projects. See ## File System.
+```
+
+### Where to put a file
+
+```
+Type of file                                      → Destination
+final document the user should keep               → workspace/<filename>
+draft, sketch, intermediate state, scratch        → workspace/tmp/{task_id}/<filename>
+mission deliverable (multi-task initiative)       → workspace/missions/<mission_name>/<filename>
+Living UI project file                            → workspace/living_ui/<name>_<hash>/...
+```
 
-## Proactive Behavior
+### Lifecycle rules
 
-You activate on schedules (hourly/daily/weekly/monthly).
+- `workspace/` (root): never auto-cleaned. Anything you save here persists until the user deletes it.
+- `workspace/tmp/{task_id}/`: created automatically by `task_manager._prepare_task_temp_dir(task_id)` when a task starts. Cleaned by `task_manager.cleanup_all_temp_dirs(...)` on `task_end` AND on agent startup (excluding currently-restored tasks). Use this for anything you don't need after the task ends.
+- `workspace/missions/<name>/`: never auto-cleaned. The mission's `INDEX.md` is what future-you reads to restore context.
+- `workspace/living_ui/<name>_<hash>/`: managed via `living_ui_actions`. Do not rename or delete by hand. See `## Living UI`.
 
-Read PROACTIVE.md for more instruction.
+### Path discipline
+
+- Always use absolute paths when invoking actions: `agent_file_system/workspace/<...>`. Never relative paths.
+- Inside an action result you may receive a path; pass it through verbatim. Do not normalize.
+- Filenames: lowercase, snake_case or kebab-case, no spaces. Example: `tsla_analysis_2026_05_04.pdf`.
+- For task-scoped files use the actual `task_id`, not a guess. The harness sets `task.temp_dir` on task creation; the path is `agent_file_system/workspace/tmp/{task_id}/`.
+
+### Missions: when to create one
+
+Create `workspace/missions/<mission_name>/INDEX.md` when ANY of:
+- Work spans multiple sessions or days.
+- Plan has more than ~10 todos.
+- User uses words like "project", "initiative", "ongoing", "campaign", "phase".
+- Output of this task will feed into a future task.
+
+If the answer is "no" to all, do NOT create a mission. A single complex task is enough.
+
+### Missions: scan-on-start
+
+At the start of every complex task:
+```
+1. list_folder agent_file_system/workspace/missions/
+2. If any directory name looks relevant to the user's request:
+     read_file agent_file_system/workspace/missions/<name>/INDEX.md
+3. Decide:
+     - Resume an existing mission              → continue updating its INDEX.md
+     - Create a new mission                    → copy MISSION_INDEX_TEMPLATE.md
+     - One-off complex task, not a mission     → no mission directory
+```
+
+This is non-optional. Skipping the scan causes duplicate work and lost context.
+
+### Mission INDEX.md fields
+
+Template lives at [agent_file_system/MISSION_INDEX_TEMPLATE.md](agent_file_system/MISSION_INDEX_TEMPLATE.md). Required fields:
+
+- **Goal**: what "done" looks like, with concrete deliverables.
+- **Status**: one of `Not started | In progress | Blocked | Completed | Abandoned`. Plus last task summary, last updated date.
+- **Key Findings**: distilled discoveries. The most important section. This is what future-you reads to restore context. Keep it tight and current.
+- **What's Been Tried**: approaches plus outcomes. Prevents repeating failed attempts.
+- **Next Steps**: concrete actions a fresh task can pick up immediately. Be specific enough that no further investigation is needed to start.
+- **Resources & References**: links, file paths, tools, contacts.
+- **Constraints & Notes**: deadlines, user preferences, environmental limits.
+
+### Mission INDEX.md update cadence
+
+- At task start (resuming a mission): read INDEX.md fully. Add a `Status` line for the new task.
+- During the task: append to `Key Findings` whenever you learn something durable. Append to `What's Been Tried` after any completed approach (success or failure).
+- Before `task_end`: update `Status`, write `Next Steps` so a fresh task session can pick up immediately. If the mission is done, mark `Status: Completed`.
+
+A mission with stale `Next Steps` is worse than no mission. Always leave it actionable.
+
+### What does NOT belong in workspace/
+
+- Configuration files (use `app/config/`).
+- Skills (use `skills/`).
+- Credentials (use `.credentials/`).
+- Logs (auto-go to `logs/<timestamp>.log`).
+- Editing AGENT.md / USER.md / SOUL.md / FORMAT.md (these are in `agent_file_system/`, not `workspace/`).
+
+---
+
+## Documents
+
+[agent_file_system/FORMAT.md](agent_file_system/FORMAT.md) is the source of truth for every document you generate (PDF, pptx, docx, xlsx, and any other file-format output). Read it before generating; it carries the user's brand colors, fonts, writing style, and layout rules.
+
+### FORMAT.md structure
+
+```
+## global       universal rules: brand colors, fonts, writing style, layout
+## pptx         slide-deck specifics (aspect ratio, margins, slide types, typography)
+## docx         Word document standards
+## xlsx         spreadsheet standards
+## pdf          PDF generation standards
+```
+
+The user can add more file-type sections (e.g., `## md`, `## csv`). Type-specific sections OVERRIDE `## global` for that file type.
+
+### Protocol before generating any document
+
+```
+1. grep_files "## <filetype>" agent_file_system/FORMAT.md -A 50
+   Read the file-type section in full.
+
+2. grep_files "## global" agent_file_system/FORMAT.md -A 50
+   Read the global section in full.
+
+3. If the file-type section is missing, fall back to global only.
+
+4. Apply the combined rules to your output: colors, fonts, spacing,
+   layout, writing style, language conventions, brand assets.
+
+5. After generating, verify the output matches by re-reading the produced
+   file (or summary of it). Especially for visual artifacts (PDF, pptx).
+```
+
+This is non-optional. Generating documents without reading FORMAT.md produces inconsistent outputs the user has to redo.
+
+### Action support
+
+Document generation actions in the standard action set:
+```
+create_pdf              build a PDF from markdown / text
+                        (preferred over rendering via run_python)
+convert_to_markdown     normalize office formats before further processing
+read_pdf                read a PDF with page support
+```
+
+Skills that compose document workflows (sample):
+```
+pdf, docx, pptx, xlsx          per-format end-to-end generation skills
+file-format                    format normalization and conversion
+compile-report-advance         multi-source compilation
+```
+
+If a skill exists for the target format (e.g., `pdf`), prefer invoking it (`/pdf` slash or LLM-selected) over composing actions yourself. Skills already encode the FORMAT.md read step and the right action sequence.
+
+### Updating FORMAT.md
+
+Edit when the user gives a durable formatting preference:
+```
+"always use a serif font in reports"            → ## global, font rule
+"company logo is at /path/to/logo.png"          → ## global, brand asset
+"PDF reports should have 1-inch margins"        → ## pdf, margins
+"slide decks should be 16:9 with dark theme"   → ## pptx, layout / theme
+```
+
+Edit procedure:
+```
+1. Confirm scope: "global rule for all docs, or just for <filetype>?"
+2. stream_edit FORMAT.md, write to the right section.
+3. Send the user the exact lines you wrote so they can correct.
+```
+
+DO NOT silently change FORMAT.md. The user owns their style guide.
+
+### Pitfalls
+
+- Generating a document without reading FORMAT.md. Visible inconsistency cost.
+- Mixing global and per-type rules incorrectly: per-type wins for that type, global wins everywhere else.
+- Adding a new file-type section without user consent. Ask first.
+- Storing the user's brand assets (logo URLs, colors) in MEMORY.md or USER.md instead of FORMAT.md. They belong in FORMAT.md.
+
+---
+
+## Living UI
+
+"Living UI" = generated React / HTML / single-page-app projects that have persistent state and are served from CraftBot. Each project is a self-contained mini-app (kanban board, habit tracker, dashboard, etc.) the user can interact with through their browser. Lifecycle is managed via `living_ui_actions`.
+
+Code: [app/data/action/living_ui_actions.py](app/data/action/living_ui_actions.py). File system layout: see `## File System` "Living UI projects" subsection.
+
+### What you actually do for a Living UI request
+
+You do NOT hand-write the project scaffold. The Living UI generator handles file scaffolding via the `living_ui_actions` action set. Your job is:
+1. Capture the user's intent (what is the app for, what state does it persist, what views / interactions).
+2. Apply GLOBAL_LIVING_UI.md design rules and any project-specific overrides.
+3. Use the appropriate Living UI skill (`living-ui-creator`, `living-ui-modify`, `living-ui-manager`) to drive the generator.
+
+### Skills for Living UI lifecycle
+
+```
+living-ui-creator    start a new project. Walks scaffolding + initial state design.
+living-ui-modify     edit an existing project (add features, change layout, fix bugs).
+living-ui-manager    list, inspect, archive, restart projects.
+```
+
+Prefer invoking these via slash (`/living-ui-creator`) or via LLM selection. They encode the right read-rules-first protocol and the right action sequence.
+
+### Protocol BEFORE creating any Living UI project
+
+```
+1. Read GLOBAL_LIVING_UI.md (small file, ~80 lines). It defines:
+   - Primary / secondary / accent colors
+   - Theme behavior (system / dark / light)
+   - Component preferences (preset components, no inline styles,
+     react-toastify, async spinners, toast CRUD feedback,
+     confirmation dialogs, validation, mobile responsive, etc.)
+   - Optional rules (drag-and-drop, keyboard shortcuts, item count
+     badges, search/filter, bulk selection, dark-mode-only, animations)
+   - User-defined custom rules
+
+2. Apply global rules first; only override on explicit user instruction.
+
+3. After creation, the project should respect EVERY "Always Enforced" rule
+   in GLOBAL_LIVING_UI.md (no inline styles, preset components, async
+   spinners, etc.).
+```
+
+If the user wants project-specific design that conflicts with GLOBAL_LIVING_UI.md, confirm the override before applying.
+
+### Per-project structure (what's guaranteed)
+
+Each project lives at `agent_file_system/workspace/living_ui/<name>_<hash>/`. The internal structure varies per project (different stacks possible). Only three files are guaranteed:
+
+```
+LIVING_UI.md          per-project doc: purpose, decisions, project-specific rules
+config/manifest.json  project metadata: name, hash, ports, capabilities
+logs/                 project runtime / build / console logs (timestamped)
+```
+
+For full file-system details and the do-not-rename rule, see `## File System` "Living UI projects" subsection.
+
+### Editing an existing project
+
+```
+1. read LIVING_UI.md to understand purpose + project-specific rules.
+2. list_folder the project to see what's actually there.
+3. Use living-ui-modify skill (don't hand-edit unless the skill
+   isn't suitable).
+4. After changes, the project should still respect GLOBAL_LIVING_UI.md.
+```
+
+When the project misbehaves: grep `logs/` first (frontend console output is piped there via ConsoleCapture). See `## File System` "Living UI projects" subsection for log details.
+
+### Updating GLOBAL_LIVING_UI.md
+
+Edit only when the user gives a NEW universal rule that should apply to ALL Living UI projects (e.g., "never use animations", "always include dark mode toggle"). For project-specific overrides, edit the project's own `LIVING_UI.md` instead.
+
+Edit procedure: same pattern as FORMAT.md — confirm scope, stream_edit, confirm to user.
+
+### Pitfalls
+
+- Hand-writing the project scaffold instead of using `living_ui_actions` / Living UI skills. The generator does it correctly; manual scaffolds drift from the template.
+- Using inline styles. Forbidden by GLOBAL_LIVING_UI.md.
+- Skipping the GLOBAL_LIVING_UI.md read for "simple" projects. Even simple ones should respect global rules.
+- Renaming a project directory by hand. Re-register via `living_ui_actions` instead — the manifest.json is the source of truth for the project's name.
+- Putting project-wide design changes in GLOBAL_LIVING_UI.md when they should be in the per-project LIVING_UI.md.
+
+---
+
+## Actions
+
+Actions are the only way you do anything. The runtime presents the currently-available actions to you in your prompt each turn. If you need a capability that is not in the current list, you must either expand the active action sets (see `## Action Sets`) or read the source to learn what to call.
+
+### Where actions live
+
+Built-in actions are Python files under [app/data/action/](app/data/action/). The action name does NOT always match the filename:
+
+```
+app/data/action/<file>.py             one or more @action() registrations
+app/data/action/CUSTOM_ACTION_GUIDE.md guide for authoring new actions
+app/data/action/<platform>/...        platform-specific bundles (one file may register 10+ actions)
+```
+
+Examples of files with multiple registrations:
+- `action_set_management.py` registers `add_action_sets`, `remove_action_sets`, `list_action_sets`.
+- `skill_management.py` registers `list_skills`, `use_skill`.
+- `integration_management.py` registers `list_available_integrations`, `connect_integration`, `check_integration_status`, `disconnect_integration`.
+- `discord/discord_actions.py`, `slack/slack_actions.py`, `telegram/telegram_actions.py`, `notion/notion_actions.py`, `linkedin/linkedin_actions.py`, `jira/jira_actions.py`, `github/github_actions.py`, `outlook/outlook_actions.py`, `whatsapp/whatsapp_actions.py`, `twitter/twitter_actions.py`, `google_workspace/{gmail,google_calendar,google_drive}_actions.py` each register many actions.
+
+Total registered built-in actions: roughly 195 (varies by version). The exact number is logged at startup in `logs/<timestamp>.log` — search for `Action registry loaded`.
+
+### How to discover actions
+
+You have three discovery paths. Pick by purpose.
+
+**1. By name (when you already know it).** Read the source:
+```
+read_file app/data/action/<action_name>.py
+```
+
+**2. By capability (when you do NOT know the name).** Grep descriptions and names across the folder:
+```
+grep_files 'name="' app/data/action/ -A 1            # list all action names + first description line
+grep_files 'description=' app/data/action/ -A 0      # list all descriptions
+grep_files '<keyword>' app/data/action/ -A 2 -B 1    # find actions matching a concept
+```
+
+**3. By currently-loaded set (what you can call right now).** Two options:
+- The runtime puts the current action list in your prompt every turn. That list is authoritative.
+- Call the `list_action_sets` action to see which sets are loaded plus all actions in them. Useful when the prompt list is truncated or you suspect a set is missing.
+
+### `@action(...)` decorator schema
+
+Every action is registered via the `@action` decorator at [agent_core/core/action_framework/registry.py](agent_core/core/action_framework/registry.py). When you read an action's `.py` file, these are the fields you will see:
+
+```
+name             str   required. Unique identifier the LLM uses to call the action.
+description      str   shown to the LLM. This is how you decide whether to use the action.
+mode             str   "CLI" | "ALL". Visibility filter.
+default          bool  legacy. If True, action is always available. Prefer action_sets.
+execution_mode   str   "internal" (in-process) | "sandboxed" (ephemeral venv subprocess).
+platforms        str|list  "linux" | "windows" | "darwin" | "all". Default: ["all"].
+input_schema     dict  JSON-schema-like description of parameters. Read this for param names and types.
+output_schema    dict  JSON-schema-like description of return shape. Read this to know what to expect.
+requirement      list  pip packages auto-installed in sandbox before execution.
+test_payload     dict  test input for diagnostic harness. The "simulated_mode" key bypasses real execution.
+action_sets      list  set names this action belongs to. Determines when it's loaded.
+parallelizable   bool  default True. False = action runs alone in its turn (write ops, state changes).
+```
+
+Key implications when reading an action:
+- `mode="CLI"` actions exist (e.g. `read_file`, `task_start`). They are loaded by default.
+- `parallelizable=False` actions cannot be batched. The router will sequence them. Examples: `task_update_todos`, `add_action_sets`, `remove_action_sets`.
+- `execution_mode="sandboxed"` means the action runs in a fresh venv subprocess with `requirement` packages installed automatically. `run_python` is sandboxed; most other actions are internal.
+- `default=True` means the action is in the action list regardless of which sets are loaded. Common defaults: `task_start`, `send_message`, `ignore`. Prefer adding to an `action_sets` list over using `default=True`.
+
+### Built-in action categories (orientation only — read source for current state)
+
+```
+core                     send_message, task_start, task_end, task_update_todos, ignore, wait,
+                         add_action_sets, remove_action_sets, list_action_sets,
+                         list_skills, use_skill,
+                         list_available_integrations, connect_integration,
+                         check_integration_status, disconnect_integration
+
+file_operations          read_file, grep_files, find_files, list_folder, stream_edit, write_file,
+                         read_pdf, convert_to_markdown, create_pdf
+
+shell                    run_shell, run_python
+
+web_research             web_fetch, web_search, http_request
+
+memory                   memory_search
+
+proactive / scheduler    schedule_task, scheduled_task_list, schedule_task_toggle,
+                         remove_scheduled_task, recurring_add, recurring_read,
+                         recurring_update_task, recurring_remove
+
+image                    describe_image, generate_image, perform_ocr
+
+video                    understand_video
+
+clipboard                clipboard_read, clipboard_write
+
+comms                    send_message_with_attachment
+
+living_ui                living_ui_http, living_ui_import_external, living_ui_import_zip,
+                         living_ui_notify_ready, living_ui_report_progress, living_ui_restart
+
+per-platform integrations  Discord, Slack, Telegram, Notion, LinkedIn, Jira, GitHub,
+                           Outlook, WhatsApp, Twitter, Google Workspace
+                           (each has its own bundle file; loaded via integration action sets)
+```
+
+This grouping is informal. The authoritative grouping per action is the `action_sets=[...]` list in its decorator. When in doubt, grep the source.
+
+### Calling an action
+
+You do not call actions directly in code. You emit an action decision in your turn output. Format (illustrative):
+
+```
+{"action_name": "read_file", "parameters": {"file_path": "agent_file_system/AGENT.md", "limit": 200}}
+```
+
+The router validates the name and parameters against the action's `input_schema`, then the executor runs it. The result returns as a dict matching `output_schema`. See `## Errors` for the standard `{"status": "success" | "error", ...}` envelope.
+
+### Authoring a new action
+
+If you discover the harness is missing a capability you need repeatedly:
+1. Read [app/data/action/CUSTOM_ACTION_GUIDE.md](app/data/action/CUSTOM_ACTION_GUIDE.md).
+2. Pick a similar existing action as a template (e.g. for a file op, copy `read_file.py`).
+3. Create the new file under [app/data/action/](app/data/action/) with a single `@action(...)` decorator.
+4. Register it in the right `action_sets`.
+5. Restart is required for code changes (hot-reload covers configs, NOT new action files). See `## Hot Reload`.
+
+For everything routine (existing capabilities), prefer composing existing actions over authoring new ones.
+
+---
+
+## Action Sets
+
+An action set is a named bundle of actions you load together. Loading a set makes all its actions available in your prompt; the LLM can then call them. Sets exist to keep your prompt small (only the actions you need) without sacrificing capability.
+
+Code: [app/action/action_set.py](app/action/action_set.py) (`ActionSetManager`). Set descriptions: [app/action/action_set.py](app/action/action_set.py) `DEFAULT_SET_DESCRIPTIONS`.
+
+### How sets are discovered
+
+Sets are NOT hardcoded. They are discovered dynamically by scanning every registered action's `action_sets=[...]` declaration. Any name an action declares becomes a valid set. This means:
+- Adding a new action to a new set name silently creates that set.
+- MCP servers auto-register as `mcp_<server_name>` sets via `action_set_name` in `mcp_config.json`. See `## MCP`.
+- A set with no actions is invisible (the discovery scans actions, not a static list).
+
+To list every set currently visible to the runtime, call the `list_action_sets` action.
+
+### Built-in sets (with curated descriptions)
+
+`DEFAULT_SET_DESCRIPTIONS` has explicit descriptions for these eight sets:
+
+```
+core                  Essential actions, always available
+file_operations       File and folder manipulation
+web_research          Internet search and browsing
+document_processing   PDF and document handling
+image                 Image viewing, analysis, OCR
+video                 Video analysis
+clipboard             Clipboard read/write
+shell                 Command line and Python execution
+```
+
+Any set name not in `DEFAULT_SET_DESCRIPTIONS` is presented to the LLM as `Custom action set: <name>`.
+
+### Other sets actually used by built-in actions
+
+Beyond the eight curated sets, these sets exist because actions declare them:
+
+```
+proactive             schedule_task, scheduled_task_list, recurring_*, schedule_task_toggle, ...
+scheduler             schedule_task, schedule_task_toggle (alongside proactive)
+content_creation      generate_image, create_pdf, ...
+living_ui             living_ui_http, living_ui_restart, ...
+
+per-integration sets (loaded only when the user has the integration connected):
+discord, slack, telegram_bot, telegram_user, whatsapp, twitter,
+notion, linkedin, jira, github, outlook, google_workspace
+```
+
+This list is illustrative, not authoritative. Run `list_action_sets` for the live list. Read [app/action/action_set.py](app/action/action_set.py) for the source.
+
+### `core` is always loaded
+
+[app/action/action_set.py](app/action/action_set.py) `compile_action_list`:
+
+```
+required_sets = set(selected_sets) | {"core"}
+```
+
+You cannot opt out of `core`. Whatever else you pass to `task_start`, `core` is added. `core` includes (at minimum):
+
+```
+send_message, task_start, task_end, task_update_todos, ignore, wait,
+add_action_sets, remove_action_sets, list_action_sets,
+list_skills, use_skill,
+list_available_integrations, connect_integration,
+check_integration_status, disconnect_integration,
+clipboard_read, clipboard_write
+```
+
+(Note: `clipboard_read` and `clipboard_write` are in `core`, not in a separate `clipboard` set, despite the curated description suggesting otherwise.)
+
+### How sets are loaded
+
+Three mechanisms, in order of preference:
+
+1. **At `task_start`** — pass the names in the `action_sets` parameter. The LLM-driven creator (`do_create_task`) auto-selects sets based on the task description; you can also pre-select via skill slash commands like `/pdf`. `core` is added automatically.
+2. **Mid-task** — call `add_action_sets(action_sets=[...])` or `remove_action_sets(action_sets=[...])`. The action list is recompiled and the new actions appear in the next turn's prompt.
+3. **Via skill selection** — if a skill's `SKILL.md` frontmatter has `action-sets: [...]`, those sets are auto-loaded when the skill is selected. See `## Skills`.
+
+After loading, the new actions ARE in your prompt the next turn. You do not need to re-fetch or refresh anything.
+
+### Picking the right sets
+
+Match the task's actual needs. Loading every set bloats the prompt and slows action selection.
+
+```
+Lightweight task                  core + file_operations
+Web research / lookup             core + web_research
+Document generation               core + file_operations + document_processing
+Multimedia work                   core + image (and/or video)
+Shell / scripting                 core + shell + file_operations
+Living UI work                    core + living_ui + file_operations + shell
+Proactive task setup              core + proactive
+Per-platform integration          core + <integration_name>  (e.g. core + slack)
+```
+
+Defaults that almost always make sense: `core + file_operations`. Add others as the task requires.
+
+### Tracking what is loaded
+
+Two ways to know what set is currently active for a task:
+1. The current prompt's action list (always authoritative).
+2. The `list_action_sets` action returns `{ available_sets, current_sets, current_actions }`.
+
+If you suspect a set was supposed to be loaded but isn't (an action you expect to see is missing), call `list_action_sets` to confirm before assuming you have to manually add it with `add_action_sets`.
+
+### Set lifecycle relative to a task
+
+- Sets are LOCKED when the task is created. The task's `compiled_actions` list is built once.
+- `add_action_sets` / `remove_action_sets` are the only mid-task mutations. They re-run `compile_action_list` and update the task's available actions.
+- When the task ends, the set selection is gone. The next task starts fresh.
+- Skills do NOT swap mid-task. To use a different skill, end the task and start a new one.
+
+See `## Tasks` for task-level lifecycle and `## Runtime` for how the action list reaches your prompt each turn.
+
+---
+
+## Slash Commands
+
+Slash commands are USER-invoked at the chat input. The agent does NOT call slash commands; the agent uses actions (see `## Actions`). Slash commands are documented here so you understand what the user just typed when they invoke one, and so you can answer questions about them.
+
+Sources of truth (in order of authority):
+1. Built-in command files: [app/ui_layer/commands/builtin/](app/ui_layer/commands/builtin/). One file per top-level command.
+2. Integration commands: dynamically registered from `INTEGRATION_HANDLERS` in [app/credentials/handlers.py](app/credentials/handlers.py). One slash command per registered handler.
+3. Skill commands: every skill with `user-invocable: true` (default) in its `SKILL.md` frontmatter is auto-registered as `/<skill_name>`.
+
+Run `/help` for the live list. If you need to verify a specific command, read its file.
+
+### General commands
+
+```
+/help [command]      list all commands, or detail one. Always available.
+/menu                show the main menu
+/clear               clear the conversation
+/clear_tasks         clear finished tasks (completed, failed, aborted) from the action panel
+/reset               reset the agent to its initial state
+/exit                quit the application
+/update              check for updates and update CraftBot
+/provider <name>     switch LLM provider (openai, anthropic, google, byteplus, remote)
+```
+
+### Credential and integration overview
+
+```
+/cred list           list all stored credentials across integrations
+/cred status         show connection status for every integration
+/cred integrations   list available integration types
+```
+
+`/cred` does not connect or disconnect; use `/<integration>` for that.
+
+### MCP server management
+
+```
+/mcp list                          list configured MCP servers + enabled state
+/mcp add <name> <command> [args]   register a new MCP server (stdio)
+/mcp add-json <json>               register from a full JSON entry
+/mcp remove <name>                 remove a server
+/mcp enable <name>                 enable a server (next reload picks it up)
+/mcp disable <name>                disable a server
+/mcp env <name> <KEY> <value>      set an env variable on a server entry
+```
+
+Edits go to [app/config/mcp_config.json](app/config/mcp_config.json) and are hot-reloaded. See `## MCP` and `## Configs`.
+
+### Skill management
+
+```
+/skill list                                    list installed skills + enabled state
+/skill info <name>                             show metadata + body of a skill
+/skill enable <name>                           move a skill into enabled_skills
+/skill disable <name>                          move a skill into disabled_skills
+/skill install <source>                        install from a git URL or path
+/skill create [name] [description]             scaffold a new skill (uses craftbot-skill-creator)
+/skill remove <name>                           delete a skill from skills/ directory
+/skill reload                                  rediscover skills (manual hot-reload)
+```
+
+Edits go to [app/config/skills_config.json](app/config/skills_config.json) and the [skills/](skills/) directory. See `## Skills`.
+
+### Skill direct invocation
+
+Every skill with `user-invocable: true` in its frontmatter (default) is registered as a slash command:
+
+```
+/<skill_name> [args]    invoke the skill directly
+```
+
+When the user types this, the runtime starts a task with the skill pre-selected (bypassing LLM skill selection in `do_create_task`). Examples that exist in the current build: `/pdf`, `/docx`, `/pptx`, `/xlsx`, `/weather-check`, `/get-weather`, etc. The list depends on which skills are enabled in [app/config/skills_config.json](app/config/skills_config.json).
+
+### Integration commands (auth + lifecycle)
+
+For each registered integration in `INTEGRATION_HANDLERS`, a slash command `/{integration}` is auto-registered:
+
+```
+/<integration> status                    show connection state, accounts
+/<integration> connect [...credentials]  connect (token-based) — fields depend on integration
+/<integration> disconnect [account_id]   remove a connection
+/<integration> login-qr                  for whatsapp_web (QR scan flow)
+/<integration> invite                    for OAuth-capable integrations (browser flow)
+```
+
+Currently registered (per [app/credentials/handlers.py](app/credentials/handlers.py) `INTEGRATION_HANDLERS`):
+
+```
+google              OAuth flow.   /google invite | status | disconnect
+slack               OAuth + token. /slack invite | connect <bot_token> [workspace_name] | status | disconnect
+notion              OAuth + token. /notion invite | connect <token> | status | disconnect
+linkedin            OAuth flow.   /linkedin invite | status | disconnect
+discord             Token flow.   /discord connect <bot_token> | status | disconnect
+telegram            Bot + user.   /telegram connect <bot_token> | status | disconnect
+                                  (user-account flow has additional sub-commands; see /help telegram)
+whatsapp            Web (QR).     /whatsapp login-qr [phone] | status | disconnect
+whatsapp_business   API tokens.   /whatsapp_business connect <phone_number_id> <access_token> | status | disconnect
+outlook             OAuth flow.   /outlook invite | status | disconnect
+jira                Token flow.   /jira connect ... | status | disconnect
+github              Token flow.   /github connect <token> | status | disconnect
+twitter             Token flow.   /twitter connect ... | status | disconnect
+```
+
+The exact `connect` fields per integration are defined in `INTEGRATION_REGISTRY` at [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py). Use `/help <integration>` to see what credentials it expects.
+
+### Agent-provided commands
+
+Skills can register commands at runtime via the agent command wrapper ([app/ui_layer/commands/builtin/agent_command.py](app/ui_layer/commands/builtin/agent_command.py)). These appear in `/help` alongside built-in commands. To audit what's currently registered, ask the user to run `/help` and paste the output, or read the live command registry from the running process.
+
+### When the user types a slash command
+
+If a user types a slash command and you receive the resulting task or message:
+- The runtime processes the command BEFORE you see it. Your role is to react to its outcome, not to re-execute.
+- For `/<skill_name>`, the runtime creates a task with the skill pre-selected. You take over from there.
+- For `/<integration> connect` or `/cred status`, the result lands in the chat as text. The user may then ask you to do something with the now-connected integration.
+- For `/clear`, `/clear_tasks`, `/reset`, `/exit`: state changes happen immediately. You may not have continuity with prior conversation/tasks after these.
+
+---
+
+## Configs
+
+The agent's behavior is shaped by JSON config files under [app/config/](app/config/). When you need to change settings about yourself (model, API keys, MCP servers, skills, schedules, integrations), you edit one of these files. The harness watches them and reloads automatically.
+
+This section is the source of truth for: every config file's full schema, what each key controls, the hot-reload mechanism, what does and does NOT take effect without restart, and the edit-and-verify workflow.
+
+### The six config files
+
+```
+app/config/settings.json              model, API keys, OAuth, cache, browser, memory          hot-reload
+app/config/mcp_config.json            MCP server registry                                     hot-reload
+app/config/skills_config.json         enabled / disabled skills                               hot-reload
+app/config/external_comms_config.json telegram + whatsapp listener configs                    hot-reload
+app/config/scheduler_config.json      cron schedules                                          hot-reload
+app/config/onboarding_config.json     first-run state                                         NOT watched
+```
+
+You may also encounter MCP server entries that point at standalone JSON files; those are imported at MCP load time and follow `mcp_config.json`'s lifecycle.
+
+### Editing protocol (memorize this)
+
+```
+1.  read_file <config_path>                       see current state
+2.  decide what to change
+3.  stream_edit <config_path> ...                 make the edit (preserves unrelated content)
+4.  wait ~0.5s for debounce                        the watcher coalesces rapid saves
+5.  verify the reload happened                    see "Verifying a reload" below
+6.  if no effect: check logs/<latest>.log for     [SETTINGS] / [MCP] / [CONFIG_WATCHER] errors
+    [CONFIG_WATCHER] / [MCP] / [SETTINGS] errors
+```
+
+Use `stream_edit`, never `write_file`, on configs. A whole-file rewrite risks losing unrelated keys the runtime relies on (e.g. `api_keys_configured` bookkeeping, your own `oauth` clients).
+
+If the file is malformed JSON after your edit, the reload fails and the previous in-memory config keeps running. Read the file back and fix the syntax. `[SETTINGS] JSONDecodeError` will appear in the log.
+
+### Hot-reload mechanism
+
+Source: [agent_core/core/impl/config/watcher.py](agent_core/core/impl/config/watcher.py) (`ConfigWatcher` singleton).
+
+```
+backend                  watchdog library if installed; polling (1s) fallback otherwise
+watch granularity        the watcher subscribes to each config file's PARENT DIRECTORY,
+                         then filters events by registered file path
+debounce                 0.5 seconds. Rapid saves within 500ms are coalesced into one reload.
+trigger                  on file modification:
+                           1. cancel any pending debounce timer for that path
+                           2. start a fresh 0.5s timer
+                           3. on timer fire, call the registered reload callback
+callback execution       sync callbacks run in the watcher thread. Async callbacks are
+                         scheduled on the main event loop via run_coroutine_threadsafe.
+log signature            "[CONFIG_WATCHER] Registered watch for <name>"  (at startup)
+                         "[CONFIG_WATCHER] Started watching config files"
+                         per-reload: "[SETTINGS] Reloaded ..." / "[MCP] Reloaded ..." etc.
+```
+
+### Per-config reload behavior
+
+Every watched config has a specific reload callback registered at startup ([app/agent_base.py](app/agent_base.py) `_initialize_config_watcher`):
+
+```
+settings.json
+  callback        settings_manager.reload + invalidate_settings_cache
+  effect          provider/model/API keys updated for the NEXT LLM call.
+                  An in-flight call uses the OLD config; the next turn uses the new one.
+  log signature   [SETTINGS] Reloaded ...
+
+mcp_config.json
+  callback        mcp_client.reload  (async)
+  effect          servers with enabled=true that are not connected get connected.
+                  servers that became enabled=false get disconnected.
+                  newly-added servers register their action set as mcp_<name>.
+                  tools appear in the next turn's action list (after action set is loaded).
+  log signature   [MCP] Loaded config with N server(s) ... [MCP] Connecting to '<name>' ...
+
+skills_config.json
+  callback        skill_manager.reload + ui_controller.sync_skill_commands
+  effect          skill discovery re-runs on skills/. Newly-enabled skills become
+                  selectable; disabled skills disappear. Slash commands for
+                  user-invocable skills are re-registered (/{skill_name} appears or vanishes).
+                  Effect on a running task: the active task keeps its locked skill list.
+                  New skills are only available to the NEXT task.
+  log signature   [SKILL] Reloaded skills_config ...
+
+external_comms_config.json
+  callback        registered after external_comms initialization
+  effect          telegram and whatsapp listeners start, stop, or reconfigure based on
+                  enabled / mode changes. Other platforms (discord, slack, etc.) are not
+                  in this file - they are managed by .credentials/ + /<integration> commands.
+  log signature   [EXT_COMMS] Reloaded ...
+
+scheduler_config.json
+  callback        scheduler.reload  (async)
+  effect          schedules re-parsed. New entries fire on their first matching window.
+                  Removed entries do not fire next cycle.
+                  Currently-firing tasks are not interrupted.
+  log signature   [SCHEDULER] Reloaded ...
+
+onboarding_config.json
+  callback        NONE (not watched).
+  effect          you do not edit this file. It is managed by the onboarding flow.
+                  If you change it manually, restart is required.
+```
+
+### What does NOT take effect on a config save
+
+- An action set already selected for an active task (locked at `task_start`).
+- An LLM call already in flight (uses the old config; next turn uses the new one).
+- A skill body / metadata change on a running task (skills are locked at task creation).
+- New built-in actions added by creating a new `.py` file under `app/data/action/` (code change, requires restart).
+- Changes to OS environment variables not stored in any config file (requires restart).
+- Code changes anywhere in `app/`, `agent_core/`, `agents/` (requires restart).
+
+If any of these apply, end the current task, restart only what's needed (often nothing - just start a new task), and the new config will be in force.
+
+### Verifying a reload
+
+By config:
+
+```
+settings.json
+  - check logs:  grep_files "[SETTINGS]" logs/<latest>.log -A 1
+  - or read back: read_file app/config/settings.json (confirm your edit landed)
+  - in next task: model/provider/api_key changes are observable when an LLM call fires
+
+mcp_config.json
+  - check logs:  grep_files "[MCP]" logs/<latest>.log -A 2
+  - look for:    "Connecting to '<server-name>'", "[StdioTransport] Starting subprocess"
+  - in next task: list_action_sets shows mcp_<server-name> as a registered set
+
+skills_config.json
+  - run /skill list (user-side) or
+  - call list_skills action  → confirms enabled/disabled state
+  - new /<skill_name> slash commands appear after sync_skill_commands fires
+
+external_comms_config.json
+  - check logs:  grep_files "[EXT_COMMS]" logs/<latest>.log -A 2
+  - if telegram/whatsapp enabled and started, expect connection success messages
+
+scheduler_config.json
+  - check logs:  grep_files "[SCHEDULER]" logs/<latest>.log -A 2
+  - call scheduled_task_list action  → confirms entries
+```
+
+If the log shows the reload fired but the change still isn't reflected: the change probably falls in "What does NOT take effect on a config save" above. End the current task or restart as appropriate.
+
+### Schemas
+
+The blocks below are dictionary-style: keys, valid values, and defaults. Read the actual JSON file (`read_file app/config/<name>.json`) when you need current values.
+
+<!-- schema:settings.json -->
+```
+File: app/config/settings.json
+
+version: string                  (CraftBot version this config was written for; do not edit)
+
+general:
+  agent_name: string             (the user-facing name of this agent, e.g. "CraftBot")
+  os_language: string            (BCP-47 / ISO code, e.g. "en")
+
+proactive:
+  enabled: bool                  (master switch for proactive workflow; if false,
+                                  proactive_heartbeat and planners are skipped)
+
+memory:
+  enabled: bool                  (master switch for memory_search and memory pipeline)
+  max_items: int                 (default 200; cap on MEMORY.md before pruning)
+  prune_target: int              (default 135; how many items remain after a prune)
+  item_word_limit: int           (default 150; words per stored memory item)
+
+model:
+  llm_provider: "openai" | "anthropic" | "google" | "byteplus" | "remote"
+  vlm_provider: same options
+  llm_model: string | null       (null = provider default; e.g. "claude-sonnet-4-5-20250929")
+  vlm_model: string | null
+  slow_mode: bool                (true throttles requests for rate-limited providers)
+  slow_mode_tpm_limit: int       (tokens per minute when slow_mode is true)
+
+api_keys:
+  openai: string                 (sk-...)
+  anthropic: string              (sk-ant-...)
+  google: string                 (Gemini API key)
+  byteplus: string
+
+endpoints:
+  remote_model_url: string       (for "remote" provider, e.g. Ollama base URL)
+  byteplus_base_url: string      (default https://ark.ap-southeast.bytepluses.com/api/v3)
+  google_api_base: string        (override for Gemini API base URL)
+  google_api_version: string     (override for Gemini API version)
+  remote: string                 (default http://localhost:11434; Ollama endpoint)
+
+oauth:
+  google:    { client_id, client_secret }     (used by /google invite OAuth flow)
+  linkedin:  { client_id, client_secret }     (used by /linkedin invite)
+  slack:     { client_id, client_secret }     (used by /slack invite)
+  notion:    { client_id, client_secret }     (used by /notion invite)
+  outlook:   { client_id }                    (used by /outlook invite)
+
+web_search:
+  google_cse_id: string          (Google Custom Search Engine ID for web_search action)
+
+cache:
+  prefix_ttl: int                (seconds; cache TTL for the system-prompt prefix)
+  session_ttl: int               (seconds; cache TTL for per-session state)
+  min_tokens: int                (skip caching prompts below this token count)
+
+browser:
+  port: int                      (default 7926; CraftBot browser frontend port)
+  startup_ui: bool               (auto-open browser at startup)
+
+api_keys_configured:             (BOOKKEEPING - reflects which keys are non-empty)
+  openai: bool
+  anthropic: bool
+  google: bool
+  byteplus: bool
+```
+<!-- /schema:settings.json -->
+
+<!-- schema:mcp_config.json -->
+```
+File: app/config/mcp_config.json
+
+mcp_servers: [
+  {
+    name: string                                   required, unique within file
+    description: string                            human-readable, shown to the LLM
+    transport: "stdio" | "sse" | "websocket"       default "stdio"
+    command: string                                required for stdio (e.g. "npx", "uv", "python")
+    args: [string]                                 stdio command arguments
+    url: string                                    required for sse / websocket
+    env: { KEY: VALUE }                            environment variables passed to the server process
+    enabled: bool                                  controls whether the server connects on load/reload
+    action_set_name: string                        default "mcp_<name>"; the action set tools register under
+  }
+]
+
+Patterns by transport:
+  NPX (Node):     transport="stdio"  command="npx"     args=["-y", "@org/server-name", ...optional-args]
+  Python (uv):    transport="stdio"  command="uv"      args=["run", "--directory", "<path>", "main.py"]
+  Python (pip):   transport="stdio"  command="python"  args=["-m", "<module>", ...args]
+  Remote SSE:     transport="sse"    url="http://localhost:3000/mcp"
+  Remote WS:      transport="websocket" url="ws://..."
+
+When a server is enabled and connects, all its tools become callable as actions
+under its action_set_name. To use them in a task, load that set via add_action_sets
+or via task_start's auto-selection.
+```
+<!-- /schema:mcp_config.json -->
+
+<!-- schema:skills_config.json -->
+```
+File: app/config/skills_config.json
+
+auto_load: bool                  default true; if false, no skills are loaded at startup
+enabled_skills: [skill_name]     skills available for selection / slash invocation
+disabled_skills: [skill_name]    explicitly turned off; loader sets enabled=false
+project_skills_dir: string       default "skills"; where SKILL.md directories are discovered
+
+Skills are discovered by scanning <project_skills_dir>/<name>/SKILL.md.
+A skill in disabled_skills is loaded but flagged disabled (the LLM does not see it).
+A skill not listed in either is loaded and enabled by default if auto_load is true.
+
+To enable a skill: move its name from disabled_skills to enabled_skills.
+To remove a skill entirely: also delete the directory under skills/.
+SKILL.md frontmatter fields: see ## Skills.
+```
+<!-- /schema:skills_config.json -->
+
+<!-- schema:external_comms_config.json -->
+```
+File: app/config/external_comms_config.json
+
+telegram:
+  enabled: bool                  master switch for the telegram listener
+  mode: "bot" | "mtproto"        bot = Bot API; mtproto = user-account API
+  bot_token: string              required for mode=bot (from @BotFather)
+  bot_username: string           the bot's @username (without the @)
+  api_id: string                 required for mode=mtproto (from my.telegram.org)
+  api_hash: string               required for mode=mtproto
+  phone_number: string           required for mode=mtproto (E.164 format)
+  auto_reply: bool               if true, incoming messages route to the agent
+
+whatsapp:
+  enabled: bool                  master switch for whatsapp listener
+  mode: "web" | "business"       web = WhatsApp Web (Playwright); business = Cloud API
+  session_id: string             web mode: cached browser session
+  phone_number_id: string        business mode (from Meta business)
+  access_token: string           business mode
+  auto_reply: bool
+
+NOTE: Other platforms (discord, slack, gmail, notion, linkedin, outlook,
+google, jira, github, twitter) do NOT live in this file.
+- Their credentials live under .credentials/<platform>.json.
+- OAuth client_id/secret for some live in settings.json's "oauth" section.
+- Connect/disconnect via /<platform> commands.
+See ## Integrations and ## Slash Commands.
+```
+<!-- /schema:external_comms_config.json -->
+
+<!-- schema:scheduler_config.json -->
+```
+File: app/config/scheduler_config.json
+
+enabled: bool                                master switch for the scheduler
+schedules: [
+  {
+    id: string                               unique identifier
+    name: string                             human-readable
+    instruction: string                      what the agent should do when fired
+    schedule: string                         natural language OR cron (see formats below)
+    enabled: bool                            individual schedule on/off
+    priority: int                            1-100, lower = higher priority
+    mode: "simple" | "complex"               task mode for the spawned task
+    recurring: bool                          true = stays after firing; false = one-shot
+    action_sets: [string]                    sets to load before the task fires
+    skills: [string]                         skills to inject before the task fires
+    payload: { type: string, ... }           passed to react()'s trigger.payload
+                                             type drives workflow routing (see ## Runtime):
+                                              "memory_processing", "proactive_heartbeat",
+                                              "proactive_planner", "scheduled", ...
+  }
+]
+
+Schedule formats (parser at app/scheduler/parser.py):
+  Natural:  "every day at 3am"
+            "every sunday at 5pm"
+            "every 30 minutes"
+            "every 3 hours"
+            "tomorrow at 9am"
+            "in 2 hours"
+            "in 30 minutes"
+            "at 3pm"
+            "immediate"
+  Cron:     "0,30 * * * *"
+            "0 7 * * *"
+            "0 8 1 * *"
+
+Built-in schedules (do NOT remove):
+  memory-processing  every day at 3am   payload.type="memory_processing"
+  heartbeat          0,30 * * *         payload.type="proactive_heartbeat"
+                                         skill: heartbeat-processor
+  day-planner        every day at 7am   payload.type="proactive_planner" scope=day
+  week-planner       every sunday at 5pm payload.type="proactive_planner" scope=week
+  month-planner      0 8 1 * *          payload.type="proactive_planner" scope=month
+```
+<!-- /schema:scheduler_config.json -->
+
+<!-- schema:onboarding_config.json -->
+```
+File: app/config/onboarding_config.json
+
+hard_completed: bool                  wizard finished (collected user_name, language, tone, etc.)
+soft_completed: bool                  conversational interview task finished
+hard_completed_at: ISO timestamp | null
+soft_completed_at: ISO timestamp | null
+user_name: string
+agent_name: string
+agent_profile_picture: string | null
+
+This file is NOT hot-reloaded. It is managed by the onboarding flow.
+Do NOT edit this file as part of normal operation.
+```
+<!-- /schema:onboarding_config.json -->
+
+### Common edits and recipes
+
+Switch LLM provider:
+```
+read_file app/config/settings.json
+stream_edit app/config/settings.json
+   model.llm_provider: "openai" → "anthropic"
+   model.llm_model: "<old>"     → "claude-sonnet-4-5-20250929"
+api_keys.anthropic must be set or the next LLM call fails (see ## Models).
+```
+
+Set an API key (when user provides one):
+```
+stream_edit app/config/settings.json
+   api_keys.<provider>: ""        → "<key>"
+   api_keys_configured.<provider>: false → true
+```
+
+Enable an MCP server already in the file:
+```
+stream_edit app/config/mcp_config.json
+   mcp_servers[i].enabled: false → true
+   if env requires a token, fill it
+```
+
+Add a new MCP server: see `## MCP` for the full recipe.
+
+Enable / disable a skill:
+```
+stream_edit app/config/skills_config.json
+   move <name> between enabled_skills and disabled_skills
+```
+
+Add a recurring schedule: prefer the `schedule_task` or `recurring_add` actions
+over editing scheduler_config.json directly. They validate the schedule expression.
+See `## Proactive`.
+
+### Pitfalls
+
+- JSON syntax errors silently keep the OLD config in memory. The reload fires, the
+  parser fails, the manager logs the error, and the previous state remains active.
+  Always verify after editing.
+- Editing `version` in settings.json does nothing useful and may confuse the next install.
+- `api_keys_configured` is bookkeeping. If you set a key, also flip the boolean.
+- `core` action set is hardcoded as always-included (see `## Action Sets`). You cannot
+  disable it via config.
+- The watcher subscribes to parent DIRECTORIES, so creating a new file in app/config/
+  is detected, but the file must be explicitly registered for any reload to fire.
+- Sandboxed actions (run_python with requirements) install their packages on first
+  call, NOT on config save. The config has no effect on action sandboxes.
+
+---
+
+## MCP
+
+MCP (Model Context Protocol) servers extend your tool inventory at runtime. Use MCP when you need a capability that no built-in action covers and no skill can compose. Each connected MCP server registers its tools as actions under a dedicated action set, callable through the same action interface as everything else.
+
+Code: [agent_core/core/impl/mcp/client.py](agent_core/core/impl/mcp/client.py) (`MCPClient`, singleton). Config: [app/config/mcp_config.json](app/config/mcp_config.json). Schema in `## Configs`.
+
+### How MCP fits in
+
+```
+mcp_config.json (your edit)
+        │
+        ▼
+MCPClient.initialize() at startup     OR    MCPClient.reload() on hot-reload
+        │
+        ▼
+for each enabled server:
+   spawn subprocess (stdio) OR open connection (sse/websocket)
+   discover its tools
+   register tools as actions in action set "mcp_<server_name>"
+        │
+        ▼
+to use: load the action set in a task (auto-selected, or via add_action_sets)
+        │
+        ▼
+LLM calls the tool just like any other action
+```
+
+The action set name is `mcp_<name>` by default, or whatever `action_set_name` is set to in the entry. After a successful connect, expect log lines like:
+
+```
+[MCP] Connecting to '<name>' (stdio): <command> <args>
+[MCP] Successfully connected to '<name>' with N tools
+[MCP] Registered N tools from server '<name>' into action set 'mcp_<name>'
+```
+
+### Pre-defined servers in this codebase
+
+The shipped `mcp_config.json` contains roughly 157 server entries (most `enabled: false`). Examples of always-shipped, commonly-enabled ones:
+
+```
+filesystem            @modelcontextprotocol/server-filesystem      file ops on cwd
+playwright-mcp        @playwright/mcp                              browser automation
+amadeus-hotels-mcp    travel API                                    hotels search
+github-mcp            @modelcontextprotocol/server-github           GitHub API
+```
+
+Categories present in the shipped config: filesystem, browser automation, calendar/email/notes, finance/markets/crypto, productivity, OS integrations, fitness, search, media, AI/image, e-commerce, dev tools, security, design, analytics, real estate. To enumerate: `grep_files '"name":' app/config/mcp_config.json` returns the full list.
+
+Before adding a NEW server, check the existing entries. The capability you need may already be there as `enabled: false` — flipping the flag is safer than adding a duplicate.
+
+### Add or enable a server (recipe)
+
+```
+1. read_file app/config/mcp_config.json
+2. Decide:
+     - The server already exists with enabled: false  → flip to true (skip to step 5)
+     - You need a new server                         → continue
+3. web_search "<capability> MCP server"
+   Common naming patterns:
+     @modelcontextprotocol/server-<name>      official servers
+     @<org>/<name>-mcp                        community servers
+     GitHub repos following the MCP spec
+4. stream_edit app/config/mcp_config.json
+   Append to mcp_servers array. Use the schema from ## Configs.
+   Set enabled: true. Set env keys (API tokens, etc.) if required.
+5. Wait ~0.5s for the watcher to debounce.
+6. Verify: see "Verifying a server is live" below.
+7. If verification fails, see "Failure modes and log signatures".
+```
+
+If the server's `env` requires a credential (API key, OAuth token, bot token), ASK THE USER for it. Do not invent values. Empty env strings are common defaults; the server will report missing-credential errors at first tool call.
+
+### Transport patterns
+
+```
+stdio (subprocess, most common)
+  transport: "stdio"
+  command:   "npx" | "uv" | "python" | "node" | <executable>
+  args:      [...]
+  env:       { KEY: VALUE }
+  url:       (omit)
+
+  Examples:
+    NPX:        command="npx",    args=["-y", "@modelcontextprotocol/server-filesystem", "."]
+    Python uv:  command="uv",     args=["run", "--directory", "C:/path/to/server", "main.py"]
+    Python pip: command="python", args=["-m", "<module_name>"]
+    Node:       command="node",   args=["<path-to-script.js>"]
+
+sse (server-sent events, remote)
+  transport: "sse"
+  url:       "http://localhost:3000/mcp"  or  "https://<host>/mcp"
+  command:   (omit)
+  env:       (often unused; the server handles its own auth)
+
+websocket (remote)
+  transport: "websocket"
+  url:       "ws://..."  or  "wss://..."
+```
+
+If the server author provides a `claude_desktop_config.json` snippet (common pattern), copy the `command`, `args`, and `env` directly. The schema is identical.
+
+### Verifying a server is live
+
+After enabling/adding, in order of cheapness:
+
+```
+1. grep the latest log for the server's name:
+     grep_files "[MCP].*<server_name>" logs/<latest>.log -A 1
+   Expect: "Successfully connected" + "Registered N tools".
+
+2. confirm the action set is registered:
+     call list_action_sets   → look for "mcp_<server_name>" in the result.
+
+3. load the set into your task:
+     call add_action_sets({"action_sets": ["mcp_<server_name>"]})
+     The new tools appear in the next turn's action list.
+
+4. call a tool from the set.
+   If it returns status=success, you're done. If status=error, the message
+   will usually point at credentials or remote-service issues.
+```
+
+If steps 1-2 fail, the server did not connect. Go to "Failure modes" below.
+If steps 3-4 fail, the server connected but tool execution is broken. Usually credentials.
+
+### Failure modes and log signatures
+
+```
+Symptom in log                                       Likely cause              Fix
+───────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+[MCP] Failed to load MCP config from <path>: ...     malformed JSON in         re-read mcp_config.json,
+                                                     mcp_config.json           fix syntax via stream_edit
+
+[MCP] Failed to connect to '<name>' - check          missing dep / wrong path  reproduce in run_shell:
+server configuration                                                            run the exact command +
+                                                                                args. Inspect stderr.
+
+[StdioTransport] Starting subprocess: <cmd>          subprocess started but    check the next few log
+followed by no "Successfully connected"              died early                lines for stderr from
+                                                                                the subprocess.
+
+[MCP] Exception connecting to '<name>': <type>: ...  any other connect-time    type tells you the class:
+                                                     error                     FileNotFoundError = command
+                                                                                missing; ConnectionError =
+                                                                                remote unreachable.
+
+server connected, tool calls return                  missing or wrong env      ask user for the key, set
+"unauthorized" / "missing API key" / "401"           variable                   it via /mcp env <name>
+                                                                                <KEY> <value>, or
+                                                                                stream_edit the env block.
+
+server connected, tool calls hang                    wrong transport (e.g.     fix transport in config.
+                                                     sse server marked stdio)
+
+server connected, tool calls succeed but always      remote rate limited       slow down or upgrade the
+return errors after first burst                                                remote-service plan.
+```
+
+Reproducing a stdio server outside the harness:
+
+```
+run_shell "<command> <args...>"   ← run literally what's in the config
+```
+
+If the subprocess fails standalone, the harness will fail too. Fix it standalone first.
+
+### Hot-reload behavior on save
+
+`MCPClient.reload(config_path)` does the following on each `mcp_config.json` save:
+
+```
+1. re-parse mcp_config.json
+2. for each currently-connected server:
+     if not in new config OR enabled=false in new config  →  disconnect
+3. for each enabled server in new config:
+     if not currently connected                            →  connect, register tools
+4. re-register all tools as actions
+5. return { success, disconnected[], connected[], failed[], total_tools }
+```
+
+Implications:
+- Toggling `enabled` cleanly connects or disconnects a single server.
+- Editing `env` for a connected server does NOT take effect until the server reconnects. Disable then re-enable, or call `mcp_client.reload()` after the file change.
+- Tasks already running keep their LOCKED action sets. New MCP tools become callable in the NEXT task or after `add_action_sets`.
+
+### Slash commands (user-side)
+
+```
+/mcp list                                  servers + connection state
+/mcp add <name> <command> [args...]        register a stdio server
+/mcp add-json <json>                       register from a full JSON entry
+/mcp remove <name>                         remove from config
+/mcp enable <name>                         flip enabled to true
+/mcp disable <name>                        flip enabled to false
+/mcp env <name> <KEY> <value>              set/update an env var
+```
+
+The agent does NOT call slash commands. If the user has not exposed an MCP server you need, edit the config directly via `stream_edit`.
+
+### When to choose MCP vs alternatives
+
+```
+Need a capability and...
+
+an existing built-in action covers it           →  use the action  (## Actions)
+a skill could compose existing actions          →  write/use a skill (## Skills)
+a third party already ships an MCP server       →  add MCP server (here)
+the user has a connected integration            →  use integration actions (## Integrations)
+nothing exists, you have to write code          →  author a new action (## Actions)
+```
+
+MCP is for capabilities you cannot get any other way without writing Python. The cost is process management, network, and an extra credential to maintain.
+
+### Permission and disclosure
+
+- Adding/enabling an MCP server modifies your runtime tool surface. Tell the user before doing it.
+- If `env` requires credentials, ASK first. Do not write empty placeholders to "test" — that just creates noise in logs and confuses the user.
+- After successful enable, summarize what tools the new server adds (count + a few names).
+
+---
+
+## Skills
+
+A skill is a markdown file with structured instructions that get injected into your prompt when selected. Skills exist for reusable workflows and codified domain knowledge that compose existing actions. Use a skill instead of an MCP server when no new tools are needed, just better instructions.
+
+Code: [agent_core/core/impl/skill/loader.py](agent_core/core/impl/skill/loader.py) (`SkillLoader`), [agent_core/core/impl/skill/config.py](agent_core/core/impl/skill/config.py) (`SkillMetadata`, `Skill`, `SkillsConfig`), [agent_core/core/impl/skill/manager.py](agent_core/core/impl/skill/manager.py) (`SkillManager` singleton).
+
+### What a skill is
+
+```
+A directory:                  skills/<name>/
+                              ├── SKILL.md         required
+                              └── <support files>  optional, referenced by SKILL.md
+
+A SKILL.md file:              YAML frontmatter (metadata)
+                              + markdown body (instructions injected into your prompt)
+
+When selected during a task:  body appended to your context until task_end.
+                              action-sets it declares are auto-loaded.
+                              /<name> slash command is registered (if user-invocable).
+```
+
+A skill is NOT a process, NOT a tool, NOT an action. It is text instructions plus a small bundle of action-set selections. The tools it uses are existing actions (built-in, MCP, integrations).
+
+### SKILL.md format
+
+```
+---
+name: <unique_id>                      required. Snake-case or kebab-case.
+description: <one paragraph>           required. The LLM reads this to decide
+                                        when to select. Be specific about WHEN
+                                        and WHAT triggers selection. Vague
+                                        descriptions never get selected.
+argument-hint: <hint>                  optional. Shown in /help when user types
+                                        /<name>. Example: "<city>" or "<file_path>".
+user-invocable: true                   optional, default true.
+                                        true = registers /<name> slash command.
+                                        false = only LLM-selectable mid-task.
+allowed-tools: [<action_name>, ...]    optional. If non-empty, ONLY these actions
+                                        are callable while the skill is active.
+                                        Empty / omitted = no restriction.
+action-sets: [<set_name>, ...]         optional. Auto-loaded when the skill is
+                                        selected. Use this to declare what tools
+                                        the skill needs (e.g. file_operations,
+                                        web_research, mcp_<server_name>).
+---
+
+# <Skill title>
+
+<Markdown body. Headings, lists, code blocks, examples - anything you'd put
+in a procedure document. This text is appended to your prompt for the
+duration of the task.>
+```
+
+Frontmatter parsing (regex `^---\s*\n(.*?)\n---\s*\n(.*)$`):
+- The file MUST start with `---` on the first line.
+- The frontmatter MUST be valid YAML.
+- Keys may use `kebab-case` OR `snake_case`. Both `argument-hint` and `argument_hint` work; same for the others.
+- If `name` is missing, the directory name is used.
+- If `description` is missing, the first non-heading paragraph of the body is used (truncated to 200 chars).
+
+### Variable substitution in the body
+
+When a skill is invoked with arguments (e.g. `/get-weather Tokyo`), the body's variables are substituted before injection ([SkillLoader.substitute_variables](agent_core/core/impl/skill/loader.py)):
+
+```
+$ARGUMENTS         the full argument string ("Tokyo")
+$ARGUMENTS[0]      first positional arg, 0-indexed
+$ARGUMENTS[1]      second positional arg
+$0, $1, $2 ...     shorthand for $ARGUMENTS[N]
+```
+
+If the skill is selected by the LLM mid-task (not via slash invocation), arguments are typically empty and these placeholders resolve to empty strings. Write skills to handle both invocation paths.
+
+### Discovery and enable flow
+
+```
+1. SkillLoader.discover_skills(search_dirs=[skills/], config=SkillsConfig)
+   scans <project_skills_dir>/<name>/SKILL.md files
+   parses frontmatter + body via FRONTMATTER_PATTERN
+2. for each parsed skill:
+     if name in disabled_skills (skills_config.json)  -> enabled=false
+     else                                             -> enabled=true
+3. enabled skills are presented to the LLM each task turn for selection
+4. user-invocable + enabled skills are registered as /<name> slash commands
+```
+
+Discovery runs at startup AND on every save of [app/config/skills_config.json](app/config/skills_config.json). The directory itself is NOT watched, so adding a brand-new skill directory requires either editing `skills_config.json` (any save triggers rediscovery) or running `/skill reload`.
+
+### How a skill gets selected for a task
+
+Two paths:
+
+**Path 1: User invocation via slash command.** When the user types `/<skill_name> [args]`:
+```
+1. The runtime calls do_create_task(...) with pre_selected_skills=[<skill_name>]
+2. LLM skill selection is BYPASSED (user already chose).
+3. LLM action-set selection still runs, then merges with skill's action-sets.
+4. Body is injected with $ARGUMENTS substituted.
+5. Task starts. Skill stays active for the entire task.
+```
+
+**Path 2: LLM selection.** When the user makes a request without slashing in:
+```
+1. do_create_task runs LLM skill+action-set selection (single LLM call).
+2. LLM picks zero, one, or more relevant skills based on their `description`.
+3. For each picked skill: body injected, action-sets merged, task starts.
+4. Skills picked stay active until task_end.
+```
+
+Skills CANNOT be swapped mid-task. To change skills, end the task and start a new one. Action sets CAN be swapped mid-task (see `## Action Sets`).
+
+### `allowed-tools` restriction
+
+When `allowed-tools` is non-empty in the frontmatter, the action filter narrows to ONLY those names while the skill is active. Use this for safety-critical skills where you want to prevent the LLM from straying. Leave empty (the default) for normal skills.
+
+### `action-sets` auto-loading
+
+When a skill is selected, every name in its `action-sets` is added to the task's action sets. The merger logic (in `do_create_task` at [app/internal_action_interface.py](app/internal_action_interface.py)):
+
+```
+final_action_sets = dedup(skill.action_sets + llm_selected_action_sets)
+```
+
+A skill that needs `web_research`, `file_operations`, and an MCP server should declare:
+```
+action-sets:
+  - web_research
+  - file_operations
+  - mcp_<server_name>
+```
+
+Don't rely on the LLM to pick the right sets. Declare them.
+
+### Adding a new skill
+
+Three paths, in order of preference:
+
+**1. Use the built-in `craftbot-skill-creator` skill.**
+```
+User runs:    /craftbot-skill-creator <name> <description>
+or LLM picks craftbot-skill-creator mid-task
+```
+This skill walks through the scaffold (writes the SKILL.md, sets up the directory, suggests action-sets). Most reliable path.
+
+**2. Install from a git repo.**
+```
+1. read_file app/config/skills_config.json       (avoid duplicates)
+2. web_search "<capability> SKILL.md github"     (or known skill repos)
+3. run_shell "git clone <url> skills/<name>"
+4. stream_edit app/config/skills_config.json
+     - move <name> from disabled_skills (if present) to enabled_skills
+     - or just add it to enabled_skills if new
+5. wait ~0.5s for hot-reload
+6. verify: /skill list (user-side) or call list_skills action
+```
+
+**3. Author by hand.**
+```
+1. mkdir skills/<name>
+2. write_file skills/<name>/SKILL.md
+   (use the format above; copy a similar existing skill as template)
+3. stream_edit app/config/skills_config.json to add to enabled_skills
+4. wait ~0.5s for hot-reload
+5. verify
+```
+
+After adding, the skill is available to the NEXT task. The currently-running task (if any) keeps its locked skill list.
+
+### Enable and disable
+
+A skill's enabled state is governed by its presence in `enabled_skills` vs `disabled_skills` in [app/config/skills_config.json](app/config/skills_config.json):
+
+```
+enabled_skills:    [<name>, ...]    skills available for LLM selection / slash invocation
+disabled_skills:   [<name>, ...]    explicitly OFF (loaded but invisible)
+not in either:                       loaded as enabled if auto_load=true (default)
+```
+
+Toggle via `stream_edit` on `skills_config.json`, OR via the user-side commands `/skill enable <name>` / `/skill disable <name>`. Both go through the same hot-reload path.
+
+### Verifying changes
+
+After enable / disable / install:
+
+```
+1. grep_files "[SKILL]" logs/<latest>.log -A 1     (confirm reload fired)
+2. action: list_skills                              (returns the live list)
+3. user-side: /skill list                           (same data, different UI)
+4. /<skill_name>                                    (only works if user-invocable=true
+                                                     AND enabled, else 404)
+```
+
+### Skill vs MCP vs action vs prompt - when to choose
+
+```
+Capability needs new code or external service                         -> MCP server (## MCP)
+Capability needs new code, isolated to the agent                      -> author an action (## Actions)
+Capability already exists, just needs orchestration / domain steps    -> skill (here)
+Just want to nudge the LLM with a one-off instruction                 -> put it in the user message,
+                                                                          NOT in a skill
+```
+
+Skills shine for: multi-step workflows ("first check X, then if Y, do Z"), domain expertise ("when generating slides, follow these design rules"), and codified procedures the LLM should follow exactly every time.
+
+### Pitfalls
+
+- A skill with a vague `description` will never get auto-selected. Be specific about triggers.
+- A skill that declares `action-sets` it doesn't actually need bloats the prompt.
+- A skill with `allowed-tools` that's too narrow will hit dead ends mid-task. Test before shipping.
+- Forgetting to add the skill to `enabled_skills` after a fresh install. It stays invisible. Always verify.
+- Editing a SKILL.md body of an installed skill: the change applies to the NEXT task. The currently-running task keeps the cached version.
+- Body too long: skill body is injected into every prompt for the task. Keep it tight.
+
+### Pre-shipped skills (sample)
+
+The shipped `skills/` directory contains around 100+ entries. Most are disabled by default; flip them via `enabled_skills` in `skills_config.json` to use. Examples currently enabled in this build:
+
+```
+get-weather                  weather lookup via Playwright + BBC Weather
+weather-check                similar pattern, alternative source
+craftbot-skill-creator       authoring new skills
+craftbot-skill-improve       refining an existing skill
+predict-stock-next-week      stock prediction workflow
+docx, pptx, xlsx, pdf        document generation per file format
+file-format                  format normalization
+playwright-mcp               browser automation steering
+living-ui-creator,
+living-ui-modify,
+living-ui-manager            Living UI project lifecycle
+compile-report-advance       multi-source report compilation
+```
+
+To enumerate the full installed set: `list_folder skills/` or `read_file app/config/skills_config.json`. To inspect a specific skill before enabling: `read_file skills/<name>/SKILL.md`.
+
+---
+
+## Integrations
+
+You can help the user connect external integrations directly through chat. Most token-based integrations can be fully driven by you: collect the credential from the user, call `connect_integration` with it, and the listener auto-starts. OAuth integrations require the user to run a slash command that opens a browser — your job is to walk them through it. Treat connecting an integration like helping a non-technical friend: tell them exactly where to go, what to copy, and what to paste back.
+
+Code: [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py) (`INTEGRATION_REGISTRY`, `connect_integration_token`, `connect_integration_oauth`, `connect_integration_interactive`). Handlers: [app/credentials/handlers.py](app/credentials/handlers.py) (`INTEGRATION_HANDLERS`).
+
+### What's wired in
+
+11 integrations registered in `INTEGRATION_REGISTRY`. Each has an `auth_type` that determines how connection happens:
+
+```
+id                  display name        auth_type                description
+─────────────────   ─────────────────   ──────────────────────   ──────────────────────────────
+google              Google Workspace    oauth                    Gmail, Calendar, Drive
+slack               Slack               both (oauth + token)     Team messaging
+notion              Notion              both (oauth + token)     Notes and databases
+linkedin            LinkedIn            oauth                    Professional network
+discord             Discord             token                    Community chat
+telegram            Telegram            token_with_interactive   Messaging platform
+whatsapp            WhatsApp            interactive (QR scan)    Messaging via Web
+whatsapp_business   WhatsApp Business   token                    WhatsApp Cloud API
+jira                Jira                token                    Issue tracking
+github              GitHub              token                    Repos, issues, PRs
+twitter             Twitter/X           token                    Tweets, timeline
+```
+
+To enumerate at runtime: call the `list_available_integrations` action. To check what's already connected: `check_integration_status`.
+
+### The agent's connection toolkit (actions)
+
+```
+list_available_integrations()                  → returns full registry + connected state for each
+check_integration_status(integration_id)       → status of one integration
+connect_integration(integration_id, ...)       → token-based connect (requires credentials)
+disconnect_integration(integration_id)         → remove connection
+```
+
+`connect_integration` is the workhorse for token-based flows. The exact required fields depend on the integration. Read [app/data/action/integration_management.py](app/data/action/integration_management.py) for the action's input_schema.
+
+### Auth-type playbook
+
+The user just asked you to connect an integration. Here's what you do for each `auth_type`:
+
+```
+auth_type "token"
+  Driven entirely from chat by you. Steps:
+    1. Tell user where to obtain the credential (links + scopes below).
+    2. User pastes the credential in chat.
+    3. You call connect_integration(integration_id, credentials={...}).
+    4. Verify with check_integration_status.
+
+auth_type "oauth"
+  Cannot be fully driven from chat. The user must run a slash command that
+  opens a browser. Steps:
+    1. Confirm settings.json has the right oauth.<platform> client_id and
+       client_secret. If empty, tell the user to register an OAuth app at
+       the platform's developer console (links below) and paste the IDs.
+       You can stream_edit settings.json once they paste.
+    2. Tell user: "Run /<platform> login (or /<platform> invite). It will
+       open a browser. Authorize, then come back."
+    3. Wait for user to confirm. Do NOT poll.
+    4. Call check_integration_status to confirm connection.
+
+auth_type "both"
+  Two paths. Pick based on user preference:
+    - User has CraftOS bot/app available     → /<platform> invite (OAuth)
+    - User has their own bot token / app     → connect_integration with token
+  Default to whichever the user already mentioned. If unclear, ask.
+
+auth_type "interactive" (whatsapp)
+  Requires a QR scan from the user's phone. Steps:
+    1. Tell user: "Run /whatsapp login. A QR code will appear. Scan it with
+       WhatsApp on your phone (Settings → Linked Devices → Link a Device)."
+    2. Wait for user to confirm scan.
+    3. Verify with check_integration_status.
+
+auth_type "token_with_interactive" (telegram)
+  Token is the primary path; the same as "token". Telegram has additional
+  user-account flows (login-user) that are interactive — only invoke if the
+  user explicitly wants user-account access (not bot).
+```
+
+Never invent a credential. If the user has not provided one, ask. If the user pastes something that doesn't match the expected format, point out what was expected before calling `connect_integration`.
+
+### Required fields and where to obtain them
+
+The fields each token integration needs (from `INTEGRATION_REGISTRY`):
+
+```
+slack
+  bot_token         (required, "xoxb-..." — Bot User OAuth Token)
+  workspace_name    (optional, friendly label)
+  Where to get it:
+    1. Go to https://api.slack.com/apps → Create New App (from scratch).
+    2. OAuth & Permissions → add scopes (chat:write, channels:read,
+       channels:history, users:read, etc. depending on use).
+    3. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-...).
+
+notion
+  token             (required, "secret_..." — Internal Integration Secret)
+  Where to get it:
+    1. Go to https://www.notion.so/my-integrations → New integration.
+    2. Pick a workspace and a name. Submit.
+    3. Copy the "Internal Integration Secret".
+    4. In Notion, share the relevant pages/databases with the integration
+       (the "..." menu on each page → Add connections).
+
+discord
+  bot_token         (required — Bot Token from a Discord application)
+  Where to get it:
+    1. Go to https://discord.com/developers/applications → New Application.
+    2. Bot tab → Add Bot → "Reset Token" → copy.
+    3. Enable required intents (Message Content, Server Members, etc.).
+    4. OAuth2 → URL Generator → bot scope + permissions → invite bot to server.
+
+telegram (bot)
+  bot_token         (required — from @BotFather)
+  Where to get it:
+    1. On Telegram, message @BotFather.
+    2. /newbot → set name and username (must end in "bot").
+    3. @BotFather replies with the token. Copy and paste.
+
+whatsapp_business
+  access_token      (required — Meta Cloud API access token)
+  phone_number_id   (required — phone number ID from Meta Business)
+  Where to get it:
+    1. Go to https://developers.facebook.com → My Apps → Create App
+       (Business type) → Add Product → WhatsApp.
+    2. From the WhatsApp config: copy the temporary access token AND the
+       phone_number_id of the test number (or your own once verified).
+    3. For production, generate a permanent token via System User.
+
+jira
+  domain            (required — e.g. mycompany.atlassian.net, no https)
+  email             (required — your Atlassian account email)
+  api_token         (required — Atlassian API token)
+  Where to get it:
+    1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
+    2. Create API token → label it → copy.
+
+github
+  access_token      (required — Personal Access Token, "ghp_..." or "github_pat_...")
+  Where to get it:
+    1. Go to https://github.com/settings/tokens → Generate new token.
+    2. For full repo access, classic token with repo, workflow, read:org scopes;
+       fine-grained tokens work for specific repos.
+    3. Copy the token (only shown once).
+
+twitter
+  api_key             (required — Consumer Key)
+  api_secret          (required — Consumer Secret)
+  access_token        (required)
+  access_token_secret (required)
+  Where to get it:
+    1. Go to https://developer.twitter.com → Projects & Apps → create an app.
+    2. Keys and tokens tab: regenerate Consumer Keys, then Access Token and Secret.
+    3. Apps need at least Read+Write user-context permissions for posting.
+```
+
+For OAuth integrations (no fields, but client_id/client_secret in `settings.json` `oauth.<platform>`):
+
+```
+google
+  client_id, client_secret in settings.json → oauth.google
+  Where to get it:
+    1. Go to https://console.cloud.google.com/apis/credentials.
+    2. Create OAuth 2.0 Client ID → Desktop app or Web application.
+    3. Copy client_id and client_secret.
+    4. Enable APIs you need: Gmail API, Google Calendar API, Google Drive API.
+    5. After saving keys to settings.json, user runs /google login.
+
+linkedin
+  client_id, client_secret in settings.json → oauth.linkedin
+  Where to get it:
+    1. Go to https://www.linkedin.com/developers/apps.
+    2. Create app → set redirect URL (the CraftBot OAuth callback).
+    3. Verify app, request access to required products.
+    4. Copy Client ID and Client Secret.
+    5. After saving keys to settings.json, user runs /linkedin login.
+
+slack OAuth (alternate to bot token)
+  client_id, client_secret in settings.json → oauth.slack
+  User runs /slack invite (uses CraftOS-hosted app) or set up your own.
+
+notion OAuth (alternate to integration token)
+  client_id, client_secret in settings.json → oauth.notion
+  Most users prefer the token path (simpler).
+```
+
+### End-to-end chat-driven connection example
+
+A canonical chat-driven flow for `github`:
+
+```
+User: "connect my github"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", task_description="Connect user's GitHub")
+
+Agent (inside the task):
+  send_message: "I can connect GitHub. I'll need a Personal Access Token.
+                 To create one:
+                 1. Go to https://github.com/settings/tokens
+                 2. Click 'Generate new token (classic)'
+                 3. Pick the scopes you need (repo, workflow, read:org for full access)
+                 4. Generate and copy the token (it's only shown once)
+                 Paste it here when ready."
+
+User: "ghp_abc123xyz..."
+
+Agent:
+  connect_integration(
+    integration_id="github",
+    credentials={"access_token": "ghp_abc123xyz..."}
+  )
+  → returns {status: "success", message: "..."}
+
+Agent:
+  check_integration_status(integration_id="github")
+  → confirms connected, lists account name
+
+  send_message: "Connected. You're authenticated as <username>. You can now
+                 ask me to read your repos, manage issues, or open PRs."
+  task_end
+```
+
+For `oauth` integrations the analogous flow:
+
+```
+User: "connect my google account"
+
+Agent:
+  Check settings.json oauth.google. If client_id/client_secret are empty,
+  walk the user through registering an OAuth app at console.cloud.google.com,
+  collect the IDs, stream_edit settings.json, then continue.
+
+  send_message: "Now run `/google login` in chat. A browser will open.
+                 Authorize CraftBot, then come back here and tell me when
+                 you're done."
+
+User: "done"
+
+Agent:
+  check_integration_status(integration_id="google")
+  → if connected: confirm + list scopes/account
+  → if not: ask user to retry, mention common issues (popup blocked,
+            wrong account picked, scopes denied)
+```
+
+### Listener auto-start
+
+After a successful `connect_integration` call, listeners auto-start for platforms that support push-style messaging. From `PLATFORM_MAP`:
+
+```
+whatsapp     → whatsapp_web listener
+telegram     → telegram_bot AND telegram_user listeners
+google       → google_workspace listener
+jira         → jira listener
+github       → github listener
+twitter      → twitter listener
+```
+
+For `slack`, `notion`, `discord`, `linkedin`, `outlook`, `whatsapp_business`: connection works but listener-style auto-reply is not configured at this layer (some are handled separately via `external_comms_config.json` for telegram/whatsapp specifically).
+
+### Verifying a connection
+
+After any connect attempt:
+
+```
+1. check_integration_status(integration_id)         → returns success + account display
+2. /cred status (user-side)                          → overview of all integrations
+3. grep_files "[<platform>]" logs/<latest>.log     → look for connect / auth errors
+```
+
+If `check_integration_status` returns "Not connected" right after a successful `connect_integration` call, something is wrong. Common: the credential validated but the listener failed to start (check logs for that platform's tag).
+
+### Disconnect
+
+```
+disconnect_integration(integration_id, account_id?)
+```
+
+`account_id` is optional. Pass it when there are multiple accounts on one platform (e.g. multiple Slack workspaces) and you want to keep the others. Omit to disconnect everything for that integration.
+
+The user can also `/<platform> disconnect [account_id]`.
+
+### Common failure modes
+
+```
+Symptom                                            Likely cause              Fix
+─────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+"Bot token is required" / "Token is required"      missing credential        ask user, retry
+                                                   in connect_integration
+
+connect succeeds, but tool calls return            scope insufficient        user re-creates token
+"Forbidden" / "Insufficient scope"                                            with proper scopes
+
+oauth connect: browser doesn't open                missing client_id/secret  walk user through
+                                                   in settings.json          registering OAuth app
+                                                                              and pasting IDs
+
+oauth connect: "redirect_uri_mismatch"             redirect URL wrong in     fix redirect URL in
+                                                   the developer console     developer console
+
+whatsapp QR: timeout                               user did not scan in time tell user to retry,
+                                                                              ensure phone has network
+
+jira: 401 / 403 on tool calls                      domain or email wrong     user re-checks domain
+                                                                              format and Atlassian email
+
+twitter: invalid signature                         API tier doesn't allow    user upgrades Twitter API
+                                                   the operation             tier (free is read-only)
+
+connection works once, fails next session          token expired (some       user regenerates and
+                                                   GitHub fine-grained       reconnects
+                                                   tokens have short TTL)
+```
+
+When in doubt: read the action's error message in full, then check `logs/<latest>.log` for the integration's tag.
+
+### When to use integration actions vs MCP
+
+Some integrations have BOTH built-in actions (via this section's connection flow) AND a corresponding MCP server (e.g. `github`, `notion`, `slack`). Pick:
+
+```
+You need basic CRUD via the user's account                    → built-in integration (here)
+You need rich tool surface, custom workflows, or a feature
+the built-in action doesn't expose                            → MCP server (## MCP)
+The user has both connected                                   → use the integration first;
+                                                                 fall back to MCP if missing a verb
+```
+
+The built-in integrations cover the common 80%; MCP covers the long tail.
+
+### Permission and disclosure
+
+- ALWAYS tell the user what credentials you need and where to get them. Never paste a vague "give me your token".
+- ALWAYS confirm the credential format roughly matches before submitting (e.g., GitHub PAT starts with `ghp_` or `github_pat_`). If it doesn't, ask the user to verify.
+- ALWAYS mask tokens in your replies. Don't echo back the full credential — use a prefix or a `...` truncation.
+- ALWAYS verify connection success before declaring victory.
+- NEVER write the token to memory, MEMORY.md, USER.md, or chat history beyond the immediate connect step. The handler stores it under `.credentials/<platform>.json` (see `## File System` for the do-not-print rule).
+
+### Using an integration during a task
+
+Connecting is one job; *using* an integration in a task is another. Each integration's source directory may carry an `INTEGRATION.md` reference doc — non-obvious workflows, identity formats, error meanings, and quirks that don't fit in action `input_schema` descriptions.
+
+Two location patterns (try the first; fall back to the second):
+- `craftos_integrations/integrations/<name>/INTEGRATION.md` — directory-style integrations (e.g. [whatsapp_web](craftos_integrations/integrations/whatsapp_web/INTEGRATION.md))
+- `craftos_integrations/integrations/<name>.md` — single-file integrations (e.g. [discord.md](craftos_integrations/integrations/discord.md), [gmail.md](craftos_integrations/integrations/gmail.md), [slack.md](craftos_integrations/integrations/slack.md))
+
+**Consult one before asking the user for input the integration could probably look up itself.** Common case: the user says "send a WhatsApp message to X" and you're tempted to ask for their own phone number — don't. The bridge already knows the logged-in user's identity. The INTEGRATION.md spells out which action returns it.
+
+Other times to grep an INTEGRATION.md:
+- An action returns an error you don't understand.
+- A workflow needs more than one action and you're unsure of the order or which fields to pass between them.
+- A field value looks unfamiliar (e.g. ends in `@lid`, `@c.us`, `@g.us`) and you're tempted to "clean it up" — these are real identity formats; pass them verbatim.
+
+If the file is missing for an integration you need, fall back to grepping the integration's source directory.
+
+---
+
+## Models
+
+You generate every response through an LLM. The user can ask you to change provider or model in chat, and you can drive that change. This section covers: providers, the model registry, LLM vs VLM vs embedding, the right way to switch (with a critical gotcha), per-provider caching strategy, and rate-limit handling.
+
+Code: [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py) (`LLMInterface`), [agent_core/core/models/model_registry.py](agent_core/core/models/model_registry.py) (`MODEL_REGISTRY`), [app/models/factory.py](app/models/factory.py) (`ModelFactory.create`), [app/ui_layer/settings/model_settings.py](app/ui_layer/settings/model_settings.py) (`PROVIDER_INFO`).
+
+### Three interface types
+
+The same provider serves up to three "interfaces":
+
+```
+LLM         text generation. The main chat brain. Required.
+VLM         vision-language model. Used for image actions (describe_image, OCR).
+EMBEDDING   text embedding. Used for memory_search semantic indexing.
+```
+
+Each interface picks its model independently. `settings.json` `model.llm_provider` and `model.vlm_provider` can point at different providers if you want (e.g., `anthropic` for text, `gemini` for vision).
+
+### Providers and what they support
+
+From [MODEL_REGISTRY](agent_core/core/models/model_registry.py):
+
+```
+provider     LLM default model            VLM default model           EMBEDDING default        notes
+─────────    ──────────────────────       ──────────────────────      ──────────────────────   ─────────────────────────────
+openai       gpt-5.2-2025-12-11           gpt-5.2-2025-12-11          text-embedding-3-small   OpenAI-hosted
+anthropic    claude-sonnet-4-5-20250929   claude-sonnet-4-5-20250929  (none — no embedding)    Claude models
+gemini       gemini-2.5-pro               gemini-2.5-pro              text-embedding-004       Google Gemini
+byteplus     seed-1-6-250915              seed-1-6-250915             skylark-embedding-...    BytePlus-hosted
+remote       llama3.2:3b                  llava:7b                    nomic-embed-text         Ollama or OpenAI-compat
+deepseek     deepseek-chat                (none)                      (none)                   text only
+moonshot     moonshot-v1-8k               (none)                      (none)                   text only
+grok         grok-3                       grok-4-0709                 (none)                   xAI
+minimax      MiniMax-Text-01              (none)                      (none)                   text only
+```
+
+If you set `model.llm_model: null` in settings.json, the default from MODEL_REGISTRY is used. Set an explicit string to override.
+
+A provider with `(none)` for VLM cannot be used as `vlm_provider`. If the user asks for vision but only has a text-only provider configured, tell them to set a separate `vlm_provider` (or use `byteplus` / `anthropic` / `openai` / `gemini` for vision).
+
+### Provider-name vs settings-key mismatch (gotcha)
+
+The provider names used in code and in `model.llm_provider` are not always identical to the `api_keys.<key>` names:
+
+```
+provider name   settings.json api_keys field   /provider command alias
+─────────────   ─────────────────────────       ──────────────────────
+openai          api_keys.openai                 openai
+anthropic       api_keys.anthropic              anthropic
+gemini          api_keys.google                 gemini    (note: provider name is "gemini" but the key is stored under "google")
+byteplus        api_keys.byteplus               byteplus
+deepseek        api_keys.deepseek               deepseek
+grok            api_keys.grok                   grok
+remote          (none — uses endpoints.remote)  remote
+```
+
+When setting an API key for Gemini, edit `api_keys.google`, NOT `api_keys.gemini`. Same translation in the `api_keys_configured` block.
+
+### Model section schema (in settings.json)
+
+```
+model:
+  llm_provider:        string        e.g. "anthropic"
+  vlm_provider:        string        e.g. "anthropic"  (often same as llm_provider)
+  llm_model:           string|null   null = use MODEL_REGISTRY default for the provider
+  vlm_model:           string|null   null = use MODEL_REGISTRY default
+  slow_mode:           bool          true = throttle requests to avoid 429s
+  slow_mode_tpm_limit: int           tokens per minute when slow_mode is true (e.g. 25000)
+```
+
+Full settings.json schema is in `## Configs`.
+
+### How LLMInterface picks the model
+
+At construction (and on `reinitialize_llm`), `ModelFactory.create(provider, interface, model_override, ...)`:
+
+```
+1. Looks up the provider in MODEL_REGISTRY[provider][interface].
+2. If model_override is set, uses it. Otherwise uses the registry default.
+3. Wires up the right client: OpenAI SDK, Anthropic SDK, Gemini client, BytePlus
+   wrapper, or Ollama HTTP for "remote".
+4. Returns ctx with provider, model, client/handles, base URL, etc.
+```
+
+The LLMInterface is constructed ONCE at startup (and reconstructed by `reinitialize_llm`). It is NOT recreated when settings.json is hot-reloaded. This is the most important gotcha in this section — see "Switching provider or model" below.
+
+### Switching provider or model — through chat
+
+The user asks: "switch to GPT-4" or "use Gemini" or "I'd like to try Claude".
+
+There are TWO mutation paths. Pick the right one based on what's changing:
+
+**Path A: Same-provider model swap (e.g. claude-sonnet-4 → claude-opus-4)**
+
+Edit `settings.json` and the change applies on the NEXT LLM call. The cache invalidates on save; the existing client uses the new model name from the next call onward.
+
+```
+1. read_file app/config/settings.json
+2. stream_edit:
+     model.llm_model: "<old>" → "<new>"
+     (also model.vlm_model if user wants vision swap)
+3. wait ~0.5s for hot-reload
+4. send_message confirming the swap took effect on next turn
+```
+
+**Path B: Provider switch (e.g. anthropic → openai)**
+
+`stream_edit` ALONE is not enough. The LLMInterface holds the old provider's client. You must trigger `reinitialize_llm`, which is exposed only via the `/provider` slash command.
+
+```
+1. Ensure api_keys.<settings_key> for the new provider is set.
+   Remember the gemini → "google" name translation.
+   If empty: ask the user for a key, then stream_edit api_keys + api_keys_configured.
+2. Tell the user to run:    /provider <name> [<api_key>]
+   Examples:    /provider openai sk-...
+                /provider anthropic
+                /provider gemini AIza...
+3. The slash command:
+     - saves to settings.json (settings, api_keys, env)
+     - calls agent.reinitialize_llm(<provider>) which rebuilds the LLMInterface
+4. Verify by waiting for the next LLM-driven response; mention the new provider
+   is in effect.
+```
+
+DO NOT just stream_edit `model.llm_provider` and call it done. The cache will say the new provider, but the LLMInterface will still use the old one until reinit. Symptoms of getting this wrong: replies still come from the old model, or LLMConsecutiveFailureError if the old client now lacks credentials.
+
+If the user cannot or will not run the slash command, the alternative is restarting CraftBot. State that explicitly.
+
+### Setting a missing API key (no provider switch)
+
+If the user just provides a new key for the CURRENT provider (e.g., they updated their Anthropic key):
+
+```
+1. stream_edit settings.json
+     api_keys.<settings_key>: "<old or empty>" → "<new>"
+     api_keys_configured.<settings_key>: false → true
+2. Hot-reload picks up the new key on next LLM call.
+3. If unsure whether the existing client cached the old key, recommend the user
+   run /provider <current> <new_key> to rebuild the client cleanly.
+```
+
+### Connection testing
+
+Before declaring the switch worked, verify. There's a built-in test using
+[app/config/connection_test_models.json](app/config/connection_test_models.json) (a tiny model + 1-token request per provider).
+
+```
+1. read_file app/config/connection_test_models.json   (see what model is used to test)
+2. test_provider_connection(provider, api_key)        helper at app/models
+                                                       (or wait for the user's first
+                                                        response to confirm)
+```
+
+The cheapest verification is just sending a `send_message` and waiting for the reply to come back without `LLMConsecutiveFailureError`.
+
+### Slow mode (rate-limit handling)
+
+If the user hits 429s (provider rate limit):
+
+```
+slow_mode: true                  pace requests
+slow_mode_tpm_limit: <N>         tokens per minute target. Common: 25000 for Anthropic free.
+```
+
+Set both. The throttle is internal to LLMInterface. After enabling, no further changes needed for the user — requests just take longer.
+
+### Per-provider caching (KV cache strategy)
+
+The harness applies different caching strategies per provider. You don't manage this directly, but knowing it helps explain cost/latency to the user:
+
+```
+provider      cache type                                managed by
+─────────     ───────────────────────────────────────   ───────────────────────────
+anthropic     ephemeral cache_control with extended TTL agent_core (built-in)
+gemini        explicit context cache (file-based)        GeminiCacheManager
+byteplus      session cache (server-side, prefix-based) BytePlusCacheManager
+openai        prompt_cache_key (automatic)               provider auto
+deepseek      prompt_cache_key                           provider auto
+grok          prompt_cache_key                           provider auto
+remote        no cross-request caching                   n/a
+```
+
+Cache TTLs come from `cache.prefix_ttl` and `cache.session_ttl` in settings.json. `cache.min_tokens` skips caching for short prompts.
+
+### Endpoint overrides
+
+In `settings.json` `endpoints`:
+
+```
+remote_model_url       base URL for "remote" provider (Ollama or OpenAI-compat)
+remote                 alternate endpoint for remote (default http://localhost:11434)
+byteplus_base_url      defaults to https://ark.ap-southeast.bytepluses.com/api/v3
+google_api_base        override for Gemini API base URL
+google_api_version     override for Gemini API version
+```
+
+Use these for self-hosted, regional endpoints, or non-default Gemini API versions. For most users, leave defaults.
+
+### Consecutive-failure circuit breaker
+
+`LLMInterface._max_consecutive_failures = 5`. After 5 consecutive failed LLM calls, `LLMConsecutiveFailureError` is raised, the active task is auto-cancelled, and `LLM_FATAL_ERROR` UI event fires. Counter resets on a successful call.
+
+Common triggers: bad API key, expired key, model name typo, rate limit storm, network outage. See `## Errors` for the recovery rules. After fixing the cause, the user must START A NEW TASK (the cancelled one is gone).
+
+### Picking the right model for a job
+
+When the user is undecided:
+
+```
+Goal                                          Suggested provider
+──────────────────────────────────────────    ──────────────────────────
+General chat / coding / reasoning             anthropic (claude-sonnet-4-5)
+                                              openai (gpt-5.2)
+Vision / image understanding                  any of: anthropic, openai, gemini, byteplus, grok
+Long-context document analysis                gemini (1-2M context)
+                                              anthropic with extended cache
+Cheap bulk reasoning                          deepseek
+                                              byteplus
+Air-gapped / offline                          remote (Ollama)
+                                              point to local llama / qwen / mistral
+Strict cost control                           gemini (free tier)
+                                              deepseek (low per-token)
+```
+
+This list is opinion, not authoritative. The user has the final say.
+
+### Pitfalls
+
+- Editing `model.llm_provider` in settings.json without running `/provider` to reinitialize. The cache says new, the live LLM uses old. Always do Path B.
+- Setting `api_keys.gemini` instead of `api_keys.google`. The Gemini provider reads from the `google` key (settings_key mismatch). Same for `api_keys_configured`.
+- Choosing a `vlm_provider` whose `MODEL_REGISTRY` entry has `VLM: None`. Vision actions will fail.
+- Empty `api_keys.<provider>` for a non-remote provider triggers `MSG_AUTH` on the first call. Always check before switching.
+- Forgetting to update `api_keys_configured` when adding a key. UI bookkeeping breaks; LLM still works.
+- Running `/provider <name>` with a key but the key is for the wrong provider (e.g., pasting Anthropic key after `/provider openai`). The error surfaces on the first call. Verify keys match.
+- Switching to `remote` (Ollama) without `endpoints.remote_model_url` configured. The factory tries `http://localhost:11434` by default; if Ollama isn't running, every call fails.
+
+### Permission and disclosure
+
+- Always confirm with the user before switching provider. The active task may have cached state that doesn't transfer.
+- Always mask API keys in chat (`sk-***...***abcd`). Echo the prefix and last 4 only.
+- After a switch, send a brief confirmation: provider, model, whether vision is supported.
+- Don't change models without being asked. Stick with what the user configured.
+
+---
+
+## Memory
+
+Memory is your long-term recall. It is RAG-backed (semantic search over a vector index), not text-grep over MEMORY.md. Items reach MEMORY.md only after the daily memory-processing pipeline distills them from the event stream. You read memory via the `memory_search` action; you do NOT write MEMORY.md directly.
+
+Code: [agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) (`MemoryManager`), [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) (incremental re-indexing), [app/data/action/memory_search.py](app/data/action/memory_search.py) (action).
+
+### The pipeline
+
+```
+1. Action / message / system event happens
+        |
+        v
+2. EventStreamManager appends to EVENT.md           (full chronological log)
+        |
+        v
+3. EventStreamManager appends filtered subset to    (memory pipeline staging
+   EVENT_UNPROCESSED.md                              buffer; see filter below)
+        |
+        v
+4. Daily 3am: scheduler fires payload.type=         (or on startup if buffer
+   "memory_processing" trigger                       is non-empty)
+        |
+        v
+5. Agent runs the memory-processor skill            (set_skip_unprocessed_logging
+   reads EVENT_UNPROCESSED.md                        is True so the task's own
+   scores each event with Decision Rubric            events do not loop back)
+   distills passing events to MEMORY.md
+        |
+        v
+6. EVENT_UNPROCESSED.md is cleared
+        |
+        v
+7. memory_file_watcher detects MEMORY.md changed,
+   triggers MemoryManager.update() to reindex the
+   ChromaDB collection
+```
+
+EVENT_UNPROCESSED.md filter (events NOT staged): `action_start`, `action_end`, `todos`, `error`, `waiting_for_user`. The pipeline focuses on user-facing dialogue and important state changes. See `## File System` for full details.
+
+The Decision Rubric (Impact + Risk + Cost + Urgency + Confidence, each 1-5, threshold >= 18) lives in [PROACTIVE.md](agent_file_system/PROACTIVE.md). Do NOT duplicate it elsewhere.
+
+### MEMORY.md format
+
+```
+[YYYY-MM-DD HH:MM:SS] [type] content
+```
+
+Type values:
+```
+capability          a new tool, MCP server, or skill became available
+project             ongoing work the user is doing
+workspace           workspace contents or organization
+focus               what the user is currently focused on
+preference          a stable user preference (also goes to USER.md often)
+analysis            distilled insight from a past task
+user_complaint      something the user objected to (avoid repeating)
+system_warning      a non-fatal warning the agent should remember
+system_limit        a known limit (rate limit, model quota, etc.)
+```
+
+One fact per line. Multi-line entries break the parser.
+
+### How memory_search works
+
+`memory_search(query, top_k)` is a vector search via ChromaDB ([app/data/action/memory_search.py](app/data/action/memory_search.py)):
+
+```
+input:
+  query            string. Natural-language question or topic.
+  top_k            int, default 5. Maximum results to return.
+
+output:
+  status           "ok" | "error"
+  results          list of memory pointers:
+                     [
+                       {
+                         chunk_id:        "MEMORY.md_memory_3"
+                         file_path:       "MEMORY.md"
+                         section_path:    "Memory"
+                         title:           "<section title>"
+                         summary:         "<first ~150 chars of the chunk>"
+                         relevance_score: 0.0-1.0 (higher = more relevant)
+                       },
+                       ...
+                     ]
+  count            int
+```
+
+Pointers are LIGHTWEIGHT references, not full content. To read the full chunk, `read_file <file_path>` and find the section, OR call the manager's `retrieve_full_content(chunk_id)` if exposed via an action.
+
+Relevance score is normalized from ChromaDB's L2 distance: `relevance = 1.0 / (1.0 + distance)`. A score above ~0.6 is usually "highly relevant"; below ~0.3 is weak.
+
+### Indexed files (what memory_search can find)
+
+The MemoryManager indexes these files only ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Searches over these are semantic. Files outside this list are NOT in the vector index, even if you `read_file` them often. To find content in non-indexed files, use `grep_files` directly.
+
+### Incremental re-indexing
+
+The watcher at [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) observes the indexed files. On any change:
+
+```
+1. compute MD5 of changed file
+2. if hash differs from cached hash: remove old chunks, re-chunk, re-index
+3. cache the new hash
+```
+
+Indexing is per-section (split by markdown headers) so one change doesn't re-process the whole file. Logs:
+
+```
+[MemoryFileWatcher] Started watching: <agent_file_system path>
+Memory update complete: {'files_added': N, 'files_updated': N, 'files_removed': N, 'chunks_added': N, 'chunks_removed': N}
+```
+
+### When to use memory_search vs grep vs file read
+
+```
+Question                                         Tool
+──────────────────────────────────────────       ─────────────────────────────
+"What do I know about X?"                        memory_search(query="X")
+"What did the user say about Y last month?"      memory_search(query="user said Y") + read CONVERSATION_HISTORY.md
+"Show me all entries of a specific type"         grep_files "[type]" MEMORY.md
+"What's in USER.md right now?"                   read_file USER.md
+"Find specific text in PROACTIVE.md"             grep_files "<text>" PROACTIVE.md
+"What past tasks involved <subject>?"            grep_files "<subject>" TASK_HISTORY.md
+```
+
+memory_search is for "what do I know about" questions. Grep is for "find this exact string". Pick the right tool.
+
+### Memory pruning
+
+When MEMORY.md exceeds `memory.max_items` in settings.json (default 200), pruning kicks in:
+
+```
+1. memory-processing task includes needs_pruning=True
+2. processor evaluates each entry's relevance and recency
+3. trims down to memory.prune_target (default 135)
+4. discarded entries are dropped (not archived)
+```
+
+Pruning runs at the same time as distillation. Look for `[MEMORY] Process memory task created with pruning phase` in logs.
+
+You can request a manual prune in chat: tell the user, then either wait for next 3am cycle or (if exposed) trigger it. The agent does NOT have a direct "prune now" action.
+
+### Adding a fact you want remembered NOW (between cycles)
+
+memory-processing only runs daily at 3am (or on startup with non-empty buffer). If the user wants something remembered immediately:
+
+```
+Option 1: Add to USER.md
+  For stable user preferences (language, tone, approval rules, etc.)
+  Use stream_edit USER.md → confirm with user → edit takes effect immediately
+  USER.md is in INDEX_TARGET_FILES, so memory_search picks it up.
+
+Option 2: Wait for next pipeline run
+  Every interaction is in EVENT_UNPROCESSED.md. The 3am job will distill it.
+  Tell the user: "I'll remember that — it'll be distilled into long-term
+  memory in the next memory cycle."
+
+Option 3: Manual trigger (if user requests)
+  Some installs expose a way to fire memory_processing on demand
+  (e.g. via a slash command). If not exposed, only the user can trigger.
+  Do NOT fabricate a way.
+```
+
+### Hard rules
+
+- You MUST NOT `stream_edit` or `write_file` MEMORY.md. Only the memory processor writes there.
+- You MUST NOT edit EVENT.md, EVENT_UNPROCESSED.md, CONVERSATION_HISTORY.md, or TASK_HISTORY.md.
+- You MAY edit USER.md (with user confirmation, see `## Self-Edit`).
+- You MAY edit AGENT.md (with caution, see `## Self-Edit`).
+- Calling `grep_files` on MEMORY.md is OK for inspection, BUT for retrieval use `memory_search`. Grep misses semantic matches and skips relevance ranking.
+- The vector index lives in `chroma_db_memory/` — do NOT edit by hand.
+
+### Settings that affect memory
+
+In [app/config/settings.json](app/config/settings.json) `memory` block (see `## Configs`):
+
+```
+memory.enabled            bool. If false, memory_search returns empty + no
+                          pipeline runs. Pipeline trigger is skipped at the
+                          react level (is_memory_enabled() check).
+memory.max_items          int (default 200). Trigger threshold for pruning.
+memory.prune_target       int (default 135). Target size after a prune.
+memory.item_word_limit    int (default 150). Soft cap on words per stored item.
+```
+
+Toggling `memory.enabled` to false does NOT delete `MEMORY.md` or `chroma_db_memory/`. It just stops the pipeline from running and `memory_search` from returning results.
+
+### Pitfalls
+
+- `memory_search` returns "Memory is disabled" → check `memory.enabled` in settings.json. The user may have turned it off.
+- `memory_search` returns empty `results: []` with no error → the index may be empty (fresh install) or the query phrasing doesn't match the indexed content. Try rephrasing or `grep_files` as fallback.
+- Editing AGENT.md, USER.md, PROACTIVE.md, MEMORY.md, or EVENT_UNPROCESSED.md re-triggers re-indexing. If you make rapid edits, the watcher debounces but still consumes some time. Don't loop edit-then-search.
+- `relevance_score` is L2-distance-normalized. Don't compare scores across queries (different queries have different score distributions).
+- The `chroma_db_memory/` directory is an opaque ChromaDB store. Do not try to repair or migrate it. If corrupted, the user must delete the directory and let the manager rebuild on next startup.
+
+---
+
+## Proactive
+
+The proactive system lets you fire tasks on a schedule without a user prompt. Two parallel mechanisms exist: **recurring tasks** (in PROACTIVE.md, fired by the heartbeat) and **scheduled tasks** (in scheduler_config.json, fired by cron). Most user-facing automations belong in PROACTIVE.md.
+
+Code: [app/proactive/manager.py](app/proactive/manager.py) (`ProactiveManager`), [app/proactive/parser.py](app/proactive/parser.py), [app/proactive/types.py](app/proactive/types.py). Authority on rubric and tiers: [agent_file_system/PROACTIVE.md](agent_file_system/PROACTIVE.md).
+
+### Two mechanisms — when to use each
+
+```
+PROACTIVE.md (preferred for user automations)        scheduler_config.json (system + one-offs)
+───────────────────────────────────────────────      ────────────────────────────────────────────
+recurring_add / recurring_read /                     schedule_task / scheduled_task_list /
+recurring_update_task / recurring_remove             schedule_task_toggle / remove_scheduled_task
+
+Frequencies: hourly | daily | weekly | monthly       Schedule expressions: "every day at 3am",
+                                                     cron "0,30 * * * *", "in 2 hours",
+                                                     "tomorrow at 9am", "immediate", etc.
+
+Heartbeat (every 30 min) checks for due tasks        Each entry has its own cron, fires
+across ALL frequencies, runs each that's due,        independently. One-time entries auto-remove.
+respecting time / day filters.
+
+Decision Rubric and Permission Tiers apply.          No rubric or tier system at this level.
+                                                     Scheduled tasks just fire as configured.
+
+Use for: morning briefings, weekly reviews,          Use for: built-in schedules (memory-processing,
+recurring user-facing automations, anything          heartbeat, planners), one-time reminders
+with a permission_tier and conditions.               ("remind me at 3pm tomorrow"), system jobs.
+```
+
+The user wants a daily morning briefing? Use `recurring_add`. The user wants a one-time "remind me at 5pm"? Use `schedule_task`.
+
+### When to set up a proactive task
+
+A proactive task is justified ONLY when ALL of these are true:
+
+```
+1. The user explicitly asked for it, OR you are extending a clear recurring
+   pattern they already use.
+2. The work is repeatable, predictable, and useful enough to justify the
+   cost of running it on schedule.
+3. The output is actionable — has a clear destination (chat, file, integration).
+4. The user has consented to the cadence and the permission tier.
+5. There is no existing recurring task that does the same thing.
+```
+
+Reject the impulse to add proactive tasks aggressively. Each one consumes LLM turns on a schedule and clutters the user's mental model.
+
+DO NOT auto-create a proactive task because it "sounds useful". Always offer first, get explicit consent, then create.
+
+### When NOT to set up a proactive task
+
+```
+- One-off requests ("check the weather right now") → just do it inline.
+- Tasks with vague triggers or unclear stop conditions.
+- Tasks the user might forget they set up. Better to add as a one-time
+  reminder via schedule_task with a fixed end date.
+- Tasks that need real-time event triggers, not time-based ones (e.g. "tell
+  me when X arrives in my inbox" is better solved with an integration
+  listener, not a poll-every-hour proactive task).
+- Tasks that overlap with an existing one. Run recurring_read first.
+```
+
+### Built-in scheduler entries (do NOT remove)
+
+These ship pre-configured in [app/config/scheduler_config.json](app/config/scheduler_config.json) and run the system itself:
+
+```
+id                  schedule              purpose
+─────────────────   ──────────────────    ─────────────────────────────────────────────────
+heartbeat           0,30 * * * *          every 30 min: scan PROACTIVE.md, fire due tasks
+memory-processing   every day at 3am      distill EVENT_UNPROCESSED.md into MEMORY.md (## Memory)
+day-planner         every day at 7am      review yesterday + plan today's proactive priorities
+week-planner        every sunday at 5pm   weekly review, update Goals/Plan/Status in PROACTIVE.md
+month-planner       0 8 1 * *             1st of month 8am, monthly review
+```
+
+Removing or disabling these breaks the system. If the user wants to STOP them firing (e.g., disable proactive entirely), set `proactive.enabled: false` in `settings.json` instead.
+
+### Planners deep-dive
+
+Three time-horizon planners ship as separate skills, each owning one cadence:
+
+```
+day-planner       (skills/day-planner/SKILL.md)        daily 7am
+week-planner      (skills/week-planner/SKILL.md)       Sunday 5pm
+month-planner     (skills/month-planner/SKILL.md)      1st of month 8am
+```
+
+The fourth executor in this family is `heartbeat-processor` — not strictly a planner, but the same family pattern. It fires every 30 min and runs whatever PROACTIVE.md says is due.
+
+All four share an important property: **silent execution**. They override standard task completion rules ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md), [skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md)):
+
+```
+NO acknowledgement to user on task start.
+NO waiting for user confirmation before task_end.
+MUST call task_end immediately after the planning/execution work is done.
+MAY send_message at tier 1 (notify, no wait) when there's something user-facing.
+NEVER block on a user reply (no wait_for_user_reply=true except when proposing a new task).
+```
+
+Why: planners and heartbeat run automatically. If they wait for user confirmation each cycle, tasks pile up indefinitely.
+
+**day-planner** ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md))
+- Fires daily at 7am via scheduler.
+- Pre-flight reads: `scheduled_task_list`, PROACTIVE.md, TASK_HISTORY.md, MEMORY.md, USER.md, recent CONVERSATION_HISTORY.md.
+- Goal: "How can I help the user get SLIGHTLY closer to their goals TODAY?"
+- Output: updates the Goals / Plan / Status section in PROACTIVE.md with the day's priorities. Optionally proposes ONE new recurring or scheduled task with `wait_for_user_reply=true` and a 20-hour timeout (does NOT add the task if user doesn't reply in 20 hours).
+- Action sets loaded by default: `file_operations`, `proactive`, `scheduler`, `google_calendar`, `notion`, `web`.
+
+**week-planner** ([skills/week-planner/SKILL.md](skills/week-planner/SKILL.md))
+- Fires Sunday 5pm.
+- Reviews the past week's outcomes, updates the weekly section of Goals / Plan / Status, and may propose changes to recurring tasks (frequency tweaks, retiring stale tasks).
+
+**month-planner** ([skills/month-planner/SKILL.md](skills/month-planner/SKILL.md))
+- Fires 1st of month at 8am.
+- Long-horizon: monthly themes, big-picture goal review, retiring or renaming PROACTIVE.md tasks that no longer serve.
+
+**heartbeat-processor** ([skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md))
+- Fires every 30 min via the `heartbeat` schedule.
+- For each due task in PROACTIVE.md, picks one of two execution types:
+  - **INLINE** (default for tier 0-1, simple actions): runs the task in this heartbeat session, sends optional tier-1 notification, records outcome via `recurring_update_task add_outcome`, moves on.
+  - **SCHEDULED**: spawns a separate session via `schedule_task(schedule="immediate", ...)` when the task needs different action sets, complex multi-step work, or its own session lifecycle.
+- After processing all due tasks, calls `task_end` immediately.
+
+**Custom planners exist.** The repo also ships skills like `compliance-cert-planner` and `task-planner` for narrower cadences. They follow the same silent-execution pattern but are wired in via separate scheduler entries when needed. Read their SKILL.md to learn what they do; don't assume they're active without confirming.
+
+**Reading the planners' output.** The Goals / Plan / Status section of PROACTIVE.md is where planners speak to you. When you start a task, scan that section for current focus and recent accomplishments — that's the cheapest way to align with the user's stated direction.
+
+### One-time / immediate proactive tasks (fire-and-check-back)
+
+The most underused pattern in this section. Use it when:
+
+- The user wants something done at a SPECIFIC future moment (not on a recurring cadence).
+- The user wants something done IMMEDIATELY but in a separate session that returns a result later.
+- You're inside a task and want to spawn a parallel sub-task whose result you'll check on next time you wake up.
+- A planner has identified a concrete one-shot action ("research X tomorrow morning at 9am").
+
+These tasks fire ONCE, return a result via `send_message` and/or by writing to the workspace, and auto-remove themselves from `scheduler_config.json` after firing.
+
+Use `schedule_task` with one of these expressions:
+
+```
+"immediate"              fire NOW (queues an immediate trigger; runs as soon as
+                         the trigger queue picks it up, typically within seconds).
+"in 30 minutes"          fire 30 minutes from now.
+"in 2 hours"             fire 2 hours from now.
+"at 3pm"                 fire at 3pm today (or tomorrow if 3pm has passed).
+"at 3:30pm"              fire at 3:30pm today.
+"at 3:30pm today"        explicit today (rejects if past).
+"tomorrow at 9am"        fire 9am tomorrow.
+```
+
+Schema reminder (full table is in "Scheduled task actions" above):
+
+```
+schedule_task(
+  name="<short name>",
+  instruction="<what to do, in clear imperative voice>",
+  schedule="<expression from list above>",
+  mode="simple" | "complex",         default "simple"
+  priority=<1-100>,                   default 50
+  enabled=True,                       always true for one-shots
+  action_sets=[<sets needed>],        if known; otherwise auto-selected
+  skills=[<skills needed>],           rare for user-driven one-shots
+  payload={...}                       optional extra data for the trigger
+)
+```
+
+**When to set `mode="simple"` vs `mode="complex"` for a one-shot:**
+
+```
+simple    quick lookup, single output (3 actions or fewer). No user-approval gate. Auto-ends.
+complex   multi-step research, document generation, multi-source compile. User approval at end.
+```
+
+Default to simple for one-shots unless the work clearly needs todos.
+
+**Examples.**
+
+User says: "in 30 minutes, remind me to take the laundry out"
+
+```
+schedule_task(
+  name="Laundry reminder",
+  instruction="Send the user a brief reminder to take the laundry out.",
+  schedule="in 30 minutes",
+  mode="simple",
+)
+```
+
+User says: "research the new Apple Vision Pro reviews and give me a summary tomorrow morning at 8am"
+
+```
+schedule_task(
+  name="Apple Vision Pro review summary",
+  instruction=(
+    "Search the web for the latest Apple Vision Pro reviews from credible "
+    "tech publications. Compile a summary covering: hardware impressions, "
+    "software/UX feedback, comparison to competitors, common complaints, "
+    "common praise. Send the summary to the user via send_message."
+  ),
+  schedule="tomorrow at 8am",
+  mode="complex",
+  action_sets=["web_research", "file_operations"],
+)
+```
+
+User asks you (mid-task) to "also start checking the GitHub issue I just opened" while you're doing something else:
+
+```
+schedule_task(
+  name="Monitor GitHub issue #X",
+  instruction="Fetch the GitHub issue at <url> right now and report the latest comments and status.",
+  schedule="immediate",
+  mode="simple",
+  action_sets=["github"],
+)
+```
+
+`schedule="immediate"` queues a trigger that fires within seconds. The agent (in a fresh task) picks it up, runs the instruction, returns. The current task is unaffected.
+
+**Why this pattern matters.** It lets you parallelize: spawn a one-shot, keep working on the main task, and the user gets the spawned task's result asynchronously via send_message. It's also the right pattern when a planner identifies a discrete future action — the planner schedules the task, then ends silently, and the future-agent runs the actual work later.
+
+**One-shot lifecycle.**
+
+```
+1. schedule_task(schedule="<future moment>", ...) creates entry in scheduler_config.json.
+2. The scheduler holds it until fire_at is reached.
+3. At fire_at, scheduler emits a trigger with payload.type="scheduled" (or as configured).
+4. react() routes the trigger to the conversation/simple/complex workflow based on mode.
+5. The agent runs the instruction.
+6. After firing, the scheduler removes the entry (one-shots are auto-removed).
+7. Final result is in EVENT.md, send_message output, or workspace files (depending on instruction).
+```
+
+**Verifying a one-shot is queued:**
+
+```
+scheduled_task_list()                              ← see all entries + next fire times
+read_file app/config/scheduler_config.json         ← raw inspection
+```
+
+If a one-shot was supposed to fire but didn't, check:
+- `proactive.enabled` in settings.json
+- `enabled: true` on the entry
+- The schedule expression parsed correctly (failed parse = entry never created — check for an error in the action's return)
+- The system was running at fire time (CraftBot must be alive for the trigger to fire)
+
+### After a proactive task fires — thinking about what's next
+
+A proactive task that runs and disappears without follow-up wastes the work. After ANY proactive task (recurring or one-time) finishes, the executing agent should consider:
+
+**1. Did the task fully achieve its goal?**
+
+```
+Yes  →  record the outcome with recurring_update_task add_outcome (for recurring)
+        or just log via task_end summary (for one-shots).
+        Move on.
+
+Partially  →  record what was achieved AND what's outstanding.
+              Decide: spawn a follow-up via schedule_task for the remainder?
+              Or surface the gap to the user?
+
+No (failed)  →  record the failure with success=false.
+                Decide: was it transient (retry next cycle), approach-wrong
+                (change instruction or scope), or impossible (disable task,
+                surface to user)?
+                See ## Errors for the failure taxonomy.
+```
+
+**2. Is there a natural follow-up the user would want?**
+
+```
+The task surfaced new information that needs action  →  schedule_task immediate
+                                                         for the action; or send_message
+                                                         to the user with the finding.
+The task identified an emerging pattern              →  consider proposing a NEW recurring
+                                                         task (with user consent) to track it.
+The task confirmed nothing changed                   →  silent task_end; no follow-up needed.
+The task hit a blocker that requires user input      →  send_message with a specific question;
+                                                         do NOT schedule another attempt
+                                                         until the user replies.
+```
+
+**3. Should the recurring task itself be adjusted?**
+
+If the same recurring task has hit the SAME outcome multiple times in a row (visible in `outcome_history`), consider:
+
+```
+- Increase or decrease frequency (e.g., daily → weekly).
+- Tighten or relax conditions (e.g., add weekdays_only).
+- Update the instruction to reflect what actually works.
+- Disable the task if it's no longer useful.
+```
+
+Use `recurring_update_task` with the appropriate `updates` dict. Don't make these changes silently for tasks the user set up — confirm first.
+
+**4. Is the Goals / Plan / Status section in PROACTIVE.md still accurate?**
+
+If a proactive task accomplished or invalidated something in the planner-maintained section:
+
+```
+- Mark a "Plan" item as completed.
+- Update "Status" to reflect new state.
+- Drop a stale "Goal" if the user no longer cares.
+```
+
+Planners (day, week, month) update this section automatically on their cadence, but you can update it sooner when a task produces a clear state change. Use `stream_edit` carefully — preserve the section's structure.
+
+**5. Memory and self-edit.**
+
+If the task surfaced a stable user preference or an enduring fact, that belongs in USER.md or eventually MEMORY.md (via the daily distillation, see `## Memory`). One-time facts in EVENT.md are enough.
+
+If the task revealed an operational lesson useful to future-you, consider whether AGENT.md needs an update (see `## Self-Edit`).
+
+**6. Default behavior at the end of a proactive task:**
+
+```
+1. recurring_update_task add_outcome    (recurring tasks only)
+2. send_message at the right tier        (if there's anything user-facing)
+3. task_end                              (always)
+```
+
+That's the minimum. Steps 1 and 3 are non-optional for recurring tasks.
+
+**Anti-patterns when ending a proactive task:**
+
+- Calling `task_end` without recording an outcome on a recurring task.
+- Sending a message at higher tier than configured (tier 1 task → don't bombard with tier 2 approval requests).
+- Leaving a follow-up implicit ("the user will probably ask"). If you decided a follow-up is needed, schedule it explicitly via `schedule_task`.
+- Re-running the same logic that just failed without changing approach.
+- Loop guard: if `outcome_history` shows N consecutive failures, do NOT keep retrying. Disable the task or surface to the user.
+
+### Heartbeat behavior
+
+Every 30 min (`0,30 * * * *`):
+
+```
+1. fires payload.type="proactive_heartbeat" trigger
+2. _handle_proactive_heartbeat() in app/agent_base.py:
+     proactive_manager.get_all_due_tasks()  → filter by frequency + time + day
+     if no due tasks: return silently
+     if due tasks: create one Heartbeat task with mode=simple,
+                   action_sets=[file_operations, proactive, web_research],
+                   skill=heartbeat-processor
+3. Heartbeat task runs through the heartbeat-processor skill, which executes
+   each due task in turn, respecting permission tiers.
+4. After each task, recurring_update_task records the outcome.
+```
+
+If `proactive.enabled` is false in settings.json, step 1 fires but step 2 returns early. The task is not created.
+
+### Recurring task actions (PROACTIVE.md)
+
+```
+recurring_add(name, frequency, instruction, time?, day?, priority?, permission_tier?, enabled?, conditions?)
+  Adds a new recurring task to PROACTIVE.md.
+  frequency: "hourly" | "daily" | "weekly" | "monthly"   (REQUIRED)
+  time:      "HH:MM" 24-hour                              (recommended for daily/weekly/monthly)
+  day:       "monday".."sunday" for weekly                (for weekly)
+             "1".."31" for monthly                        (for monthly)
+  priority:  1-100, lower = higher priority. Default 50.
+  permission_tier: 0-3. Default 1. See PROACTIVE.md for semantics.
+  enabled:   bool. Default true.
+  conditions: optional list of {type: "..."} filters
+              (e.g. [{type: "market_hours_only"}, {type: "weekdays_only"}])
+  Returns:   { status, task_id, message }
+
+recurring_read(frequency?, enabled_only?)
+  Lists existing recurring tasks. Use to check for duplicates BEFORE adding.
+  frequency:    "all" | "hourly" | "daily" | "weekly" | "monthly"
+  enabled_only: bool, default true
+
+recurring_update_task(task_id, updates?, add_outcome?)
+  Modifies a task or records an execution outcome.
+  updates:     dict with any of: enabled, priority, permission_tier,
+               instruction, time, day, name
+  add_outcome: dict with result (string) and optionally success (bool)
+               USE THIS after every proactive task execution to record
+               result, even if success. The task's outcome_history (capped
+               at the most recent entries) feeds future decisions.
+
+recurring_remove(task_id)
+  Deletes a task entirely. Confirm with user first if removing a task they
+  set up.
+```
+
+### Scheduled task actions (scheduler_config.json)
+
+```
+schedule_task(name, instruction, schedule, priority?, mode?, enabled?,
+              action_sets?, skills?, payload?)
+  Adds a one-time, recurring, or immediate scheduled task.
+  schedule expression formats (validated by app/scheduler/parser.py):
+    "immediate"
+    "at 3pm" / "at 3:30pm" / "at 3:30pm today"
+    "tomorrow at 9am"
+    "in 2 hours" / "in 30 minutes"
+    "every day at 7am" / "every day at 3:30pm"
+    "every monday at 9am"
+    "every 3 hours" / "every 30 minutes"
+    cron: "0 7 * * *"
+  NOT accepted: "daily at", "every weekday", "every morning", freeform text.
+  mode:        "simple" | "complex". Default "simple".
+  payload.type drives workflow routing if set (rare; usually omit).
+
+scheduled_task_list()
+  Lists all scheduled tasks (system schedules + user-added).
+
+schedule_task_toggle(schedule_id, enabled)
+  Enables or disables a schedule without removing it.
+
+remove_scheduled_task(schedule_id)
+  Deletes a schedule. Built-in schedules can be removed but should NOT be.
+```
+
+### Setting up a proactive task — chat-driven flow
+
+User says: "remind me to drink water every 2 hours" or "set up a daily 7am morning briefing".
+
+```
+Step 1: Acknowledge and decide which mechanism
+        - Time-based + recurring + frequency matches PROACTIVE.md → recurring_add
+        - One-off, fixed time, or interval that doesn't fit hourly/daily/weekly/monthly → schedule_task
+        - Hourly with no specific time → recurring_add(frequency="hourly")
+
+Step 2: Check for duplicates
+        recurring_read(frequency="<freq>")           ← for PROACTIVE.md
+        OR scheduled_task_list()                      ← for scheduler_config.json
+        If a similar task exists, confirm with user before adding another.
+
+Step 3: Confirm the details with the user
+        - Exact instruction the agent will follow when fired
+        - Frequency / time / day
+        - Permission tier (see PROACTIVE.md). Default to tier 1 unless user
+          explicitly wants tier 0 (silent) or tier 2+ (approval).
+        - Conditions if any (weekdays only, market hours only, etc.)
+
+Step 4: Create the task
+        recurring_add(...) OR schedule_task(...)
+
+Step 5: Confirm to user
+        State the task ID, frequency, next fire time, and tier.
+        Tell them how to disable: "Run /help recurring or ask me to remove it."
+
+Step 6: When the task fires later (heartbeat-processor skill runs it):
+        - Execute the instruction
+        - Send any user-facing output via send_message (respecting tier)
+        - Call recurring_update_task with add_outcome to record the result
+```
+
+Example exchange:
+
+```
+User: "remind me to take a walk every weekday at 3pm"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", ...)
+
+Agent (inside task):
+  recurring_read(frequency="daily", enabled_only=true)
+  → no duplicate
+
+  send_message:
+    "I can set that up. Confirming:
+     - Instruction: send a reminder to take a walk
+     - Frequency: daily at 15:00
+     - Days: weekdays only
+     - Permission tier: 1 (notify and proceed without approval)
+     OK to add?"
+
+User: "yes"
+
+Agent:
+  recurring_add(
+    name="Take a walk",
+    frequency="daily",
+    instruction="Send the user a brief, friendly reminder to take a walk.",
+    time="15:00",
+    permission_tier=1,
+    conditions=[{"type": "weekdays_only"}],
+    enabled=true,
+  )
+  → returns { status: "ok", task_id: "take_a_walk_001" }
+
+Agent:
+  send_message:
+    "Done. 'Take a walk' is scheduled weekdays at 3pm. Next run:
+     <next weekday>. Tell me if you want to change it or remove it."
+  task_end
+```
+
+### Permission tiers (high-level — full table in PROACTIVE.md)
+
+```
+tier 0    silent - the task runs but does NOT message the user. Used for
+          background data collection or memory updates.
+tier 1    notify - the task runs and sends a brief notification or result.
+          Default for most user-facing automations.
+tier 2    approval - the task pauses and asks the user before doing the
+          actual work. Used for actions that change state.
+tier 3    high-risk - the task pauses, asks, AND defers to the user for
+          execution. Reserved for irreversible / external-facing actions.
+```
+
+When unsure, default to tier 1. Never set tier 0 without confirming the user actually wants silent execution.
+
+For the FULL Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold >= 18) and the per-tier behavior contract, read [PROACTIVE.md](agent_file_system/PROACTIVE.md). PROACTIVE.md owns those definitions; do NOT duplicate them.
+
+### Conditions (filtering when a task fires)
+
+The `conditions` array on a recurring task lets you filter executions:
+
+```
+{"type": "weekdays_only"}        skip Saturday/Sunday
+{"type": "market_hours_only"}    only during market hours (9:30-16:00 ET)
+{"type": "user_active"}          only when the user has been active recently
+{"type": "<custom>"}             custom predicate evaluated by heartbeat-processor
+```
+
+Read [PROACTIVE.md](agent_file_system/PROACTIVE.md) for the full list of supported conditions.
+
+### Recording outcomes — feedback loop
+
+Every recurring task should record its outcome via `recurring_update_task add_outcome` so future executions can learn from history. The `outcome_history` field on a task keeps the most recent entries (typically last 5-10).
+
+```
+After executing a proactive task, call:
+  recurring_update_task(
+    task_id="<id>",
+    add_outcome={
+      "result": "Sent the morning briefing. Calendar had 3 meetings, top priority was X.",
+      "success": True,
+    }
+  )
+```
+
+This is non-optional. Without outcome history, the task has no memory of what it did before, and decisions about whether to re-fire degrade over time.
+
+### Pitfalls
+
+- Adding a proactive task without user consent. Don't. Always offer first, get explicit yes, then create.
+- Skipping the duplicate check. Always run `recurring_read` before `recurring_add`.
+- Setting `permission_tier=0` (silent) by default. Default to 1 unless the user clearly wants silent.
+- Putting a one-off reminder in PROACTIVE.md (it'll fire forever). Use `schedule_task` for one-offs — they auto-remove.
+- Using freeform schedule expressions in `schedule_task` ("daily at 9am" is rejected; use "every day at 9am").
+- Forgetting to call `recurring_update_task add_outcome` after the task runs. Outcome history powers future decisions.
+- Removing built-in schedules (`heartbeat`, `memory-processing`, `*-planner`). The system depends on them.
+- Editing PROACTIVE.md or scheduler_config.json directly when an action exists. The actions validate inputs; manual edits can break the parser.
+
+### Verifying the schedule is set up
+
+```
+1. recurring_read(frequency="all", enabled_only=false)   ← see all entries
+2. read_file agent_file_system/PROACTIVE.md              ← inspect raw
+3. grep_files "[PROACTIVE]" logs/<latest>.log -A 1       ← startup confirmation
+4. After the next scheduled fire time, check logs and EVENT.md for execution.
+```
+
+If the task should have fired but didn't, check:
+- `proactive.enabled` in settings.json (master switch)
+- `enabled` on the task itself in PROACTIVE.md
+- `time` and `day` match the current moment
+- `conditions` are met
+- The heartbeat itself fired (`grep_files "Heartbeat" logs/<latest>.log`)
+
+### Where authority lives
+
+```
+Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold)   →  PROACTIVE.md
+Permission Tiers (0-3 detailed contract)                                    →  PROACTIVE.md
+Recurring task YAML schema                                                  →  PROACTIVE.md
+Goals / Plan / Status section (planner-maintained)                          →  PROACTIVE.md
+Schedule expression grammar                                                 →  app/scheduler/parser.py
+Heartbeat dispatch logic                                                    →  app/agent_base.py _handle_proactive_heartbeat
+PROACTIVE.md parsing / serialization                                        →  app/proactive/parser.py
+ProactiveManager API                                                        →  app/proactive/manager.py
+```
+
+This file (AGENT.md) is the operations playbook. PROACTIVE.md is the policy and schema spec. Read both when in doubt.
+
+---
+
+## Onboarding Context
+
+First-run state is tracked in [app/config/onboarding_config.json](app/config/onboarding_config.json).
+
+### Two phases
+
+| Phase | What it does | Output |
+|---|---|---|
+| Hard onboarding | Wizard collects user_name, location, language, tone, proactivity, approval rules, messaging_platform | Writes USER.md |
+| Soft onboarding | Conversational interview launched as a task | Refines USER.md, plus learnings |
+
+### Skill
+
+The soft phase uses the `user-profile-interview` skill (see [skills/user-profile-interview/SKILL.md](skills/user-profile-interview/SKILL.md)).
+
+### Templates
+
+On first run, templates from [app/data/agent_file_system_template/](app/data/agent_file_system_template/) seed `agent_file_system/` (AGENT.md, USER.md, SOUL.md, FORMAT.md, PROACTIVE.md, etc.).
+
+### Your behavior during onboarding
+
+- If `hard_completed` is false, prefer asking the user for missing profile details over assuming.
+- If `soft_completed` is false, the soft interview is pending — be open to expanding USER.md based on user input.
+- Do NOT edit `onboarding_config.json` directly — the onboarding flow manages it.
+
+---
+
+## Self-Improvement
+
+You are a self-improving agent. The harness exposes a set of mutable surfaces — config files, skill directories, action registry, memory, your own operational manual — and you have actions to modify each. Self-improvement is the deliberate use of those mutations to close capability gaps, encode learned workflows, and make future-you better at the user's tasks.
+
+There are two modes:
+
+```
+ON-DEMAND   Triggered by a user request, a capability gap, or a recognized
+            pattern mid-task. Targeted and immediate. The agent installs
+            an MCP, edits a config, or updates AGENT.md.
+
+OVER TIME   Passive. The memory pipeline distills patterns, planners review
+            and adjust PROACTIVE.md, and the agent self-edits AGENT.md when
+            a pattern recurs across many tasks. The user does not see most
+            of this; it accumulates.
+```
+
+Both modes use the same underlying mechanisms. The difference is who triggers them and how visible the change is.
+
+### What you can improve, and where the change lives
+
+```
+What                                  Where it lives                                Section
+────────────────────────────────────  ────────────────────────────────────────      ─────────────
+Tools (external services)              MCP servers in mcp_config.json                ## MCP
+Workflows (composed sequences)         Skills in skills/<name>/SKILL.md              ## Skills
+Action surface (agent-side code)       New action .py in app/data/action/            ## Actions
+External service connections           credentials via connect_integration            ## Integrations
+LLM brain                              model.* in settings.json + /provider          ## Models
+API keys                               api_keys.* in settings.json                   ## Models / ## Configs
+Recurring automations                  PROACTIVE.md via recurring_add                ## Proactive
+One-off scheduled work                 schedule_task action                          ## Proactive
+Memory recall behavior                 memory.* in settings.json + USER.md           ## Memory / ## Self-Edit
+Operational manual (this file)         AGENT.md                                      ## Self-Edit
+User preferences                       USER.md                                       ## Self-Edit
+Personality / tone                     SOUL.md                                       ## Self-Edit
+Document formatting standards          FORMAT.md                                     ## Documents
+Living UI global design                GLOBAL_LIVING_UI.md                           ## Living UI
+Hot-reload behavior                    config files (auto-applies)                   ## Configs
+```
+
+For any improvement, the right question is: which surface should change? If you can't pick one, the improvement isn't well-defined yet — talk to the user before acting.
+
+### Triggers — when to consider self-improvement
+
+```
+Trigger                                                         Improvement type
+────────────────────────────────────────────────────────────     ──────────────────────────────────────
+User explicit ask: "add an MCP for X" / "always do Y"             on-demand: install / update
+A required action is unavailable (capability gap)                  on-demand: MCP / new action / integration
+You hit the same workaround 3+ times across tasks                  over time: AGENT.md update or new skill
+Repeated user complaint of the same kind                           on-demand: USER.md or AGENT.md update
+A new environment fact (file gained a new section, integration    on-demand: AGENT.md
+  added a new endpoint, settings.json got a new key)
+Day/week/month planner identifies a candidate proactive task       on-demand: recurring_add (with consent)
+Memory distillation surfaces a stable preference                   over time: USER.md (planners can do this)
+LLMConsecutiveFailureError                                          on-demand: model/key fix (## Models)
+Action returns "Not connected" repeatedly                          on-demand: walk user through integration
+PROACTIVE.md task hits same outcome N times in a row               on-demand: recurring_update_task (tweak)
+```
+
+If none of these triggers fired, do NOT self-improve. Random tweaks bloat configs and confuse the user.
+
+### The improvement loop
+
+Replace the simple IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER with this fuller cycle:
+
+```
+1. RECOGNIZE
+   - You see a gap, friction, or explicit user ask.
+   - Name it precisely. "I cannot send messages to Slack" is precise.
+     "I should be more helpful" is not.
+
+2. CATEGORIZE
+   - Which improvement surface? (See the table above.)
+   - If multiple surfaces could serve, pick the lightest:
+     - Skill < Action < MCP < Integration in install cost.
+     - USER.md / SOUL.md < AGENT.md in self-edit risk.
+
+3. VALIDATE
+   - Is this worth doing? Will the change be used more than once?
+   - Will it hurt anything else? (e.g., a new MCP server adds tokens
+     to every prompt that loads its action set; do not add cavalierly.)
+   - Is there an existing surface that already covers this and you
+     just missed it? Run discovery actions before authoring (## Actions,
+     ## Skills, ## MCP discovery sections).
+
+4. PROPOSE
+   - Tell the user what you want to change and why, in one or two
+     sentences. Get explicit consent for anything that:
+     - Edits config files
+     - Installs new code (git clone, pip install)
+     - Asks for credentials
+     - Modifies AGENT.md or SOUL.md
+   - For trivial in-task tweaks (e.g., adding a single recurring task
+     after the user asked for it) the propose step IS the request
+     itself. Do not over-confirm.
+
+5. EXECUTE
+   - Use the right action / config edit (see per-category recipes below).
+   - One change at a time. Do not bundle a config edit with an AGENT.md
+     update with a new skill in one go — each step needs verification.
+
+6. VERIFY
+   - Run a smoke test. For each surface:
+     - MCP: list_action_sets and call one tool.
+     - Skill: /skill list and (if simple) invoke the skill.
+     - Integration: check_integration_status.
+     - Model: send_message and watch for LLMConsecutiveFailureError.
+     - PROACTIVE.md: recurring_read.
+     - AGENT.md self-edit: re-read the changed section in next turn.
+   - If smoke test fails, ROLLBACK before continuing.
+
+7. CONTINUE
+   - Resume the original task using the new capability. Do not start
+     fresh tasks unless the original task ended (e.g., LLM circuit
+     breaker fired and cancelled it).
+
+8. RECORD
+   - For recurring task outcomes: recurring_update_task add_outcome.
+   - For AGENT.md self-edits: bump version: in front matter and sync
+     to template (see ## Self-Edit).
+   - For everything else: the memory pipeline distills relevant events
+     overnight (see ## Memory). You do NOT need to manually log.
+```
+
+### Per-category recipes (cross-references)
+
+For full step-by-step recipes per surface, follow these pointers. Do not duplicate them here.
+
+```
+Add an MCP server                       →  ## MCP "Add or enable a server (recipe)"
+Author / install a skill                →  ## Skills "Adding a new skill"
+Author a new action                      →  ## Actions "Authoring a new action"
+                                            Note: requires RESTART (no hot-reload for code).
+Connect an integration                   →  ## Integrations "End-to-end chat-driven connection"
+Switch model / set API key               →  ## Models "Switching provider or model"
+Add a recurring task                     →  ## Proactive "Setting up a proactive task — chat-driven flow"
+Schedule a one-shot                       →  ## Proactive "One-time / immediate proactive tasks"
+Edit FORMAT.md                            →  ## Documents
+Edit GLOBAL_LIVING_UI.md                  →  ## Living UI
+Edit AGENT.md / USER.md / SOUL.md         →  ## Self-Edit
+Adjust memory settings                    →  ## Memory "Settings that affect memory" + ## Configs
+Adjust scheduler entries                  →  ## Configs (## scheduler_config.json schema)
+```
+
+### On-demand self-improvement examples
+
+**Example 1: User asks for a missing capability**
+```
+User: "I want you to be able to manage my Linear issues."
+
+Agent:
+  1. RECOGNIZE: No built-in Linear integration. No connected Linear via MCP.
+  2. CATEGORIZE: External service → MCP server.
+  3. VALIDATE: read mcp_config.json → check for an existing linear-mcp entry.
+     Found: "linear-mcp" exists with enabled: false.
+  4. PROPOSE: send_message: "Linear support exists as an MCP server already
+     in your config but is disabled. To enable, I need a Linear API token.
+     Get one at linear.app/settings/api → Personal API keys. Paste it here."
+  5. EXECUTE: stream_edit mcp_config.json
+       linear-mcp.env.LINEAR_API_TOKEN: "" → "<token>"
+       linear-mcp.enabled: false → true
+  6. VERIFY: wait 0.5s + grep_files "[MCP] Successfully connected to 'linear-mcp'"
+     Then: list_action_sets → confirm "mcp_linear-mcp" appears.
+     Then: add_action_sets("mcp_linear-mcp"); call a Linear tool with a
+     simple read.
+  7. CONTINUE: now do what the user originally wanted ("show me my open issues").
+  8. RECORD: nothing to do; memory pipeline picks up the event.
+```
+
+**Example 2: Mid-task capability gap**
+```
+Mid-task, you need to call a Stripe API. No Stripe integration is connected.
+
+Agent (mid-task, simple flow):
+  1. RECOGNIZE: action attempt failed; "stripe-mcp" exists but is disabled.
+  2. CATEGORIZE: MCP enable.
+  3. VALIDATE: Yes, user is asking about Stripe.
+  4. PROPOSE: send_message: "I need a Stripe API key to do this. Should I
+     enable the Stripe MCP server? You'll need to provide a Stripe secret
+     key (Test mode is fine for non-production)."
+  5. WAIT for user reply with the key. Then enable.
+  6. VERIFY + CONTINUE.
+```
+
+**Example 3: User shares a stable preference**
+```
+User: "always use a serif font in my reports going forward."
+
+Agent:
+  1. RECOGNIZE: durable formatting preference.
+  2. CATEGORIZE: FORMAT.md edit (per-doctype or global).
+  3. VALIDATE: Is this a real preference or one-off? "going forward" makes it durable.
+  4. PROPOSE: implicit (the user already asked); just confirm the scope:
+     send_message: "Got it. I'll add 'serif font' to FORMAT.md as a global
+     rule, applying to all generated docs. Confirm?"
+  5. EXECUTE: stream_edit FORMAT.md ## global section, add rule.
+  6. VERIFY: re-read the section to confirm landed correctly.
+  7. CONTINUE / RECORD as appropriate.
+```
+
+**Example 4: Repeated friction recognized over many tasks**
+```
+You've noticed across 5+ tasks that whenever you generate a PDF, you keep
+forgetting to call create_pdf vs trying to render via run_python first.
+
+Agent (when starting an unrelated PDF task and noticing the pattern):
+  1. RECOGNIZE: pattern of forgetting the right action.
+  2. CATEGORIZE: AGENT.md operational improvement (## Self-Edit).
+     This is a NON-OBVIOUS convention worth recording.
+  3. VALIDATE: yes, future-you would benefit.
+  4. PROPOSE: not always required for AGENT.md polish — but if the user
+     has a pattern of complaining about PDFs, ask. Otherwise, log it.
+  5. EXECUTE: stream_edit AGENT.md ## Documents adding a clarifying note.
+  6. VERIFY: re-read on next turn so the new instruction is in context.
+  7. RECORD: bump version in front matter; sync to template.
+```
+
+### Over-time self-improvement (passive)
+
+You don't drive this directly each turn, but it is happening:
+
+```
+Daily 3am          memory pipeline distills important events into MEMORY.md.
+                   Stable preferences, capabilities, system limits, user
+                   complaints — all surface here for future memory_search.
+
+Daily 7am          day-planner reviews context, may propose a recurring task.
+                   Updates Goals/Plan/Status section in PROACTIVE.md.
+
+Sunday 5pm         week-planner reviews the week's outcomes; may retire stale
+                   recurring tasks or adjust their frequency.
+
+1st of month 8am   month-planner reviews long-horizon goals; broader pruning.
+
+Heartbeat (30 min) executes due recurring tasks; records outcome via
+                   recurring_update_task add_outcome. Repeated failures in
+                   outcome_history feed future planner decisions.
+```
+
+You do NOT need to mimic this work in the foreground. When you complete a task, do step 8 RECORD properly and the over-time machinery picks it up.
+
+### Discovery before installation
+
+Before installing a new capability, run discovery to avoid duplicates:
+
+```
+Need a tool                  →  read_file app/config/mcp_config.json (server may exist disabled)
+                                 list_action_sets (mcp_<name> may already be loaded)
+Need a workflow              →  read_file app/config/skills_config.json (skill may exist disabled)
+                                 list_skills (live state)
+Need an integration          →  list_available_integrations (registry + connected state)
+                                 /cred status (user-side overview)
+Need a recurring task        →  recurring_read (avoid duplicate setups)
+Need a model                 →  read_file settings.json (user may have it set already)
+                                 list of supported providers in ## Models
+```
+
+The most common self-improvement mistake is adding a new entry when an existing one would have worked. Always check first.
+
+### Permission and consent rules
+
+ASK the user before:
+- Editing AGENT.md or SOUL.md (they affect every future interaction).
+- Installing anything that runs new code (git clone, pip install, npx fetch).
+- Adding or modifying anything that needs credentials.
+- Adding a recurring task (## Proactive — explicit consent rule).
+- Switching the LLM provider (it affects cost and behavior).
+- Connecting an integration.
+
+DO NOT need to ask for:
+- Updating USER.md after the user shared a clear durable preference (one-line
+  confirmation is enough: "I'll add that to USER.md").
+- Recording the outcome of a proactive task you just executed.
+- Re-reading a config file or running discovery actions.
+- Editing FORMAT.md after the user gave a one-shot formatting rule (still
+  confirm scope: "global vs file-type-specific").
+
+### Verification and rollback
+
+Every install / edit needs a smoke test. If the smoke test fails:
+
+```
+1. Revert the edit (stream_edit back, OR /mcp disable, OR /skill disable, OR
+   delete a too-broken file).
+2. Tell the user what broke and what you reverted.
+3. Do NOT try the same thing again with no changes (loop trap).
+4. Either propose a different approach or stop and ask the user.
+```
+
+If you can't tell what broke (smoke test is ambiguous): grep the latest log
+for the relevant subsystem tag. See ## Errors "Self-troubleshooting via logs"
+for the workflow.
+
+### Loop guards (mandatory)
+
+```
+- Two consecutive failed installs of the SAME capability   →  STOP. Ask the user.
+- Three consecutive failed smoke tests after edits         →  STOP. Roll back to last known good.
+                                                              Ask the user.
+- A recurring task with N consecutive failure outcomes      →  do NOT keep re-firing.
+  in outcome_history                                          recurring_update_task
+                                                              with enabled=false, then ask.
+- Any AGENT.md edit that broke a previously-working flow    →  revert immediately.
+                                                              version: bump exists for a reason
+                                                              — it's the rollback marker.
+```
+
+### Anti-patterns
+
+- Cavalier installs ("might be useful"). Every MCP server / skill / integration is a tax on prompt size and a maintenance burden. Only install when there is a concrete need.
+- Bundling improvements without verification. One change at a time, smoke test after each.
+- Self-editing AGENT.md mid-task that has nothing to do with self-improvement. AGENT.md edits belong in dedicated improvement tasks (ideally with explicit user consent), not as side effects of arbitrary work.
+- Editing SOUL.md without user consent. Personality changes apply to every interaction; never an automatic move.
+- Treating memory pipeline as a substitute for explicit self-edits. Memory captures EVENTS, not lessons. If you learned a lesson, encode it in AGENT.md so future-you sees it deterministically.
+- Skipping discovery and adding a duplicate (e.g., a second MCP server doing what an existing-but-disabled one already does).
+- Using the wrong surface (e.g., putting a one-time reminder in PROACTIVE.md, putting a system-wide formatting rule in USER.md, putting agent-personality changes in AGENT.md instead of SOUL.md).
+- Setting `permission_tier=0` (silent) on proactive tasks the user didn't explicitly ask to be silent.
+- Improving prematurely. The first time something feels rough, just push through. By the third time, propose an improvement.
+
+### A note on the goal
+
+Self-improvement is not "add capabilities". It's "be measurably more useful to THIS user, on THEIR tasks, with the smallest necessary change". The best self-improvement is often a single line added to USER.md or a stale recurring task disabled — not a new MCP server.
+
+When in doubt, do less.
+
+---
+
+## Self-Edit
+
+Three files in your own file system are agent-editable: `AGENT.md`, `USER.md`, `SOUL.md`. Each affects a different surface, has different consent rules, and a different edit procedure. Picking the wrong file is the #1 self-edit mistake.
+
+This section is the operating manual for those edits. The decision of WHEN to make a self-edit lives in `## Self-Improvement`. This section answers HOW.
+
+### Quick decision: which file to edit
+
+```
+Type of change                                          File              Consent rule
+──────────────────────────────────────────────────────  ────────────────  ──────────────────────────────
+Operational rule about HOW the agent works              AGENT.md          ask before edit
+  (workflows, conventions, schemas, recipes,
+   non-obvious gotchas)
+
+User profile fact (identity, language, time zone,       USER.md           one-line confirm
+  preferred channel, approval rules, life goals)         
+
+Personality / tone / behavior style                     SOUL.md           explicit user request only;
+  (how the agent talks, sense of humor, formality,                         ALWAYS quote back and confirm
+   emoji use, brevity vs verbosity)
+
+Document / file generation standards                    FORMAT.md         confirm scope (global vs
+  (colors, fonts, layouts per file type)                                   per-doctype)
+
+Living UI design rules                                  GLOBAL_LIVING_UI  ask if non-trivial
+  (palette, components, responsive rules)               .md
+
+Per-mission state, multi-task continuity                workspace/        no consent needed
+                                                        missions/<n>/     (it's mission-internal)
+                                                        INDEX.md
+
+Recurring or scheduled task definitions                 PROACTIVE.md      via recurring_* / schedule_*
+                                                        (or scheduler_    actions, NOT manual edit
+                                                        config.json)
+
+A one-off fact you want recalled later                  (do nothing)      memory pipeline picks it up
+                                                                          from EVENT_UNPROCESSED.md
+```
+
+If you can't pick one cleanly, the change isn't well-scoped yet. Ask the user before editing anything.
+
+### AGENT.md (this file)
+
+**Purpose.** Operational manual. Stable rules, schemas, recipes, gotchas. Read by future-you on every relevant task.
+
+**When to edit:**
+- The user explicitly asks for an operational improvement: "from now on, always X", "add a new rule about Y", "update the manual to say Z".
+- You discover a non-obvious convention through repeated experience that future-you would benefit from. Examples:
+  - A config file gained a new section after the user installed something.
+  - A workflow has a gotcha that costs a turn to rediscover each time.
+  - An action has a non-obvious parameter that the LLM keeps missing.
+
+**When NOT to edit:**
+- During a task that isn't about self-improvement. Side-quest edits get lost in unrelated tasks and bloat the manual.
+- To record one-off facts about the current user. Those go in USER.md.
+- To record project-specific findings. Those go in `workspace/missions/<name>/INDEX.md`.
+- To document something the user might change tomorrow. Stable rules only.
+- After your first encounter with a friction. Wait for the second or third. Premature additions are noise.
+
+**Edit procedure:**
+```
+1. Read the section you want to change (and its neighbors) so your edit
+   matches the surrounding tone and structure.
+2. stream_edit AGENT.md (NEVER write_file; you'd lose the rest of the file).
+3. Bump the `version:` line in the front matter when the change is material.
+4. Sync to template: also stream_edit app/data/agent_file_system_template/AGENT.md
+   so new installs get the upgrade. Both files must stay byte-identical.
+5. Re-read the changed section in your next turn so the new content lands
+   in your in-context manual.
+6. For high-impact edits, send_message to the user describing what changed
+   and where (so they can review).
+```
+
+**Style rules** (from observed errors in past edits — see `## Errors`):
+- Optimize for grep. Stable `## <Topic>` headers, HTML markers `<!-- name -->` ... `<!-- /name -->` around schemas and command blocks.
+- No ASCII art, no decorative tables for non-tabular content, no em-dash flourishes, no marketing prose.
+- Topic-anchored cross-references (`see ## Configs`), never `§N` numbers.
+- One change at a time. Don't bundle a structural reorganization with content additions.
+
+**Hard rules:**
+- Never delete a section without user consent.
+- Never demote a section header without user consent (changes grep targets).
+- Never edit AGENT.md on behalf of the agent's preferences. AGENT.md describes the harness, not what the agent personally wants.
+
+### USER.md
+
+**Purpose.** User profile. Identity, communication preferences, agent-interaction rules, life goals, personality. Indexed by `memory_search` (see `## Memory`).
+
+**Standard sections** (do NOT rename):
+```
+## Identity
+   Full Name, Preferred Name, Email, Location, Timezone, Job, etc.
+
+## Communication Preferences
+   Language, Preferred Tone, Response Style, Preferred Messaging Platform.
+
+## Agent Interaction
+   Prefer Proactive Assistance, Approval Required For, working hours, etc.
+
+## Life Goals
+   Long-term goals worth aligning to.
+
+## Personality
+   The user's personality traits the agent should adapt to.
+```
+
+**When to edit:**
+- The user shares a stable preference: "I'm in Tokyo timezone now", "I prefer terse replies", "always confirm before sending email".
+- The onboarding interview produces a fact (handled by the soft-onboarding flow, but you may add to it later).
+- A preference becomes clear from repeated user feedback (3+ instances of the same correction).
+
+**Edit procedure:**
+```
+1. Confirm the preference is durable, not one-off.
+   Quick check: "Want me to remember that for future tasks too?"
+   If yes → durable, edit USER.md.
+   If no → don't edit; let the memory pipeline catch it as a one-off.
+2. stream_edit USER.md.
+3. Write to the RIGHT section (Identity / Communication / Agent Interaction
+   / Life Goals / Personality). If it doesn't fit any, ask the user where
+   they want it.
+4. After saving, send_message confirming the exact line you wrote so the
+   user can correct it.
+```
+
+**Hard rules:**
+- ONE-LINE CONFIRM is the default. Don't over-confirm; the user already told you the preference.
+- Never silently change USER.md. The user must see the diff or your description.
+- Don't put project-specific details here. Those go in `workspace/missions/<name>/INDEX.md`.
+- Don't put SECRETS here (passwords, tokens, credentials). USER.md is indexed by memory_search and surfaces in many contexts.
+- Don't put one-off facts here. "I'm working on X today" is one-off. "I always work on X-class problems" is durable.
+
+### SOUL.md
+
+**Purpose.** Personality, tone, voice, behavior style. **Injected directly into the system prompt every turn.** This is not a reference file — it shapes every word the agent produces.
+
+**When to edit:**
+- ONLY when the user explicitly asks for a personality change: "be more formal", "stop being so cheerful", "use more emojis", "be more concise".
+
+**When NOT to edit:**
+- ANY OTHER REASON. SOUL.md is the highest-stakes file. A wrong edit changes the agent's voice for every future interaction.
+- Inferring a personality preference from indirect signals. If the user complained about tone, ASK what they want changed before editing.
+- "Improving" the soul because you think it could be better. The user owns their agent's personality.
+
+**Edit procedure:**
+```
+1. Read the current SOUL.md fully. Understand the existing voice.
+2. Quote back the exact change you propose to make:
+     "I'll change <quote of current line> to <quote of new line>. Confirm?"
+3. WAIT for the user's reply. Do NOT edit on assumption.
+4. Once confirmed: stream_edit SOUL.md.
+5. Send a short follow-up: "Done. The new voice will start in your next
+   message." (Reminds the user that the change applies immediately.)
+```
+
+**Hard rules:**
+- Always quote-back-and-confirm. No exceptions.
+- Never ADD a new section without the user explicitly asking for one.
+- Never DELETE a section without explicit confirmation.
+- Don't put operational rules here. Operational rules go in AGENT.md. SOUL.md is voice and behavior style only.
+- If the user says "stop doing X" repeatedly and X feels personality-driven, ASK before editing SOUL.md. They might just want a one-task fix, not a permanent voice change.
+
+### FORMAT.md and GLOBAL_LIVING_UI.md
+
+These are not strictly "self" files (they're for output design, not agent behavior), but the agent edits them under similar discipline. See `## Documents` and `## Living UI` for the per-file procedures.
+
+Quick rules:
+- FORMAT.md: edit when the user gives a durable formatting preference. Confirm scope (global vs file-type-specific) before writing.
+- GLOBAL_LIVING_UI.md: edit when the user supplies a new universal UI rule. For project-specific overrides, edit the per-project `LIVING_UI.md` instead.
+
+### AGENT.md ↔ template sync
+
+`agent_file_system/AGENT.md` is the LIVE file the running agent reads.
+`app/data/agent_file_system_template/AGENT.md` is the TEMPLATE that seeds new installs (see `## Onboarding Context`).
+
+```
+When you edit AGENT.md for a durable improvement, the live file and the
+template MUST stay byte-identical:
+
+1. Make the edit on whichever file you started with.
+2. Copy the change to the other file (read the section, stream_edit the same
+   change in the other file).
+3. Verify with: diff agent_file_system/AGENT.md app/data/agent_file_system_template/AGENT.md
+   (or just grep both for the new content; should appear in both).
+```
+
+If a sync drift exists (template diverges from live), the next install for a new user will ship the OLD content. That's a silent failure mode worth fixing immediately.
+
+### Verifying a self-edit
+
+After ANY edit:
+
+```
+For AGENT.md:
+  1. re-read the changed section in your next turn (it's now in your context).
+  2. confirm the front-matter version: bumped (if material change).
+  3. confirm the template was synced.
+
+For USER.md:
+  1. read the section back, paste the relevant lines to the user as
+     confirmation: "I added: <new lines>. Look right?"
+  2. memory_search will pick it up on next index pass (see ## Memory).
+
+For SOUL.md:
+  1. send a short message; the new voice should be visible in YOUR own
+     wording.
+  2. if the user immediately says "that's not what I wanted",
+     ROLL BACK to the previous SOUL.md content (you should have read it
+     before editing — keep the previous version mentally for one turn).
+```
+
+### Rollback procedure
+
+If a self-edit broke something or the user objects:
+
+```
+1. AGENT.md: stream_edit back to the previous content. Bump version: again
+   (every change deserves a version bump, even reversions).
+2. USER.md: stream_edit the offending lines back to old or remove.
+3. SOUL.md: stream_edit back. Apologize briefly. Don't re-edit until the
+   user is explicit about what they want.
+```
+
+If you don't remember the previous content (e.g., it's been many turns), grep TASK_HISTORY.md or EVENT.md for the change event and reconstruct, OR ask the user to describe what they want restored.
+
+### What ENT.md, USER.md, and SOUL.md are NOT
+
+```
+- A scratch pad. Use workspace/tmp/{task_id}/ for that.
+- A todo list. Use task_update_todos.
+- A mission record. Use workspace/missions/<name>/INDEX.md.
+- A diary. Use EVENT.md (the system writes it; you don't).
+- A memory store. Use the memory pipeline + memory_search.
+- A knowledge base for arbitrary user data. Anything that isn't profile,
+  tone, or operational rule does not belong in these files.
+```
+
+### Anti-patterns
+
+- Editing AGENT.md for things that aren't operational rules (project state, one-off opinions, user-specific facts).
+- Editing USER.md for things that aren't user profile (mission state, one-off requests).
+- Editing SOUL.md without quote-back-and-confirm.
+- Forgetting the AGENT.md template sync. The template should never drift.
+- Adding a new section to USER.md without user consent. Stick to the standard sections.
+- Putting credentials, tokens, or secrets in any of these files. They are indexed by memory and visible in chat / logs.
+- Multiple self-edits in one turn without verification between each.
+- Editing AGENT.md silently as part of an unrelated task. Self-edits deserve their own task.
+
+### One-line summary for each file
+
+```
+AGENT.md   "How the harness works, and how to operate within it." (this file)
+USER.md    "Who the user is and what they prefer."
+SOUL.md    "How the agent sounds and behaves."
+```
+
+If a proposed edit doesn't fit cleanly into one of those three sentences, it probably belongs somewhere else.
+
+---
+
+## Glossary
+
+Quick lookup of the terms used throughout this manual. Each entry points to the section that owns the full definition. Grep this section first when an unfamiliar term shows up.
+
+```
+action                    atomic unit the LLM picks each turn                              ## Actions
+action set                named bundle of actions loaded together at task_start            ## Action Sets
+add_action_sets           action that loads additional action sets mid-task                ## Action Sets
+add_outcome               recurring_update_task field for recording execution result       ## Proactive
+agent file system         the persistent agent_file_system/ directory                      ## File System
+AGENT.md                  this file - operational manual                                    ## Self-Edit
+api_keys                  settings.json block holding provider API keys                    ## Configs / ## Models
+auth_type                 integration auth flow shape: oauth/token/both/interactive/...    ## Integrations
+ChromaDB                  vector store under chroma_db_memory/ powering memory_search      ## Memory
+complex task              multi-step task with todos + user-approval gate                  ## Tasks
+ConfigWatcher             0.5s-debounced file watcher for app/config/ files                ## Configs
+connect_integration       action that connects an external service via credentials         ## Integrations
+CONVERSATION_HISTORY.md   rolling dialogue record (do not edit)                            ## File System
+conversation mode         workflow when no task is active; only task_start/send/ignore    ## Tasks / ## Runtime
+core (action set)         always-loaded set; cannot be opted out                            ## Action Sets
+Decision Rubric           proactive task scoring (Impact/Risk/Cost/Urgency/Confidence)     PROACTIVE.md, ## Proactive
+EVENT.md                  complete chronological event log (do not edit)                   ## File System
+EVENT_UNPROCESSED.md      memory pipeline staging buffer (do not edit)                     ## File System / ## Memory
+event pipeline            flow from event -> EVENT_UNPROCESSED -> MEMORY.md                ## Memory
+FORMAT.md                 document/design standards file                                   ## Documents
+GLOBAL_LIVING_UI.md       global Living UI design rules                                    ## Living UI
+heartbeat                 scheduler entry firing every 30 min to run due proactive tasks   ## Proactive
+heartbeat-processor       skill that executes due tasks during a heartbeat                 ## Proactive
+hot-reload                config-watcher debounced 0.5s reload of /app/config/             ## Configs
+INDEX_TARGET_FILES        five files indexed by memory_search                              ## Memory
+integration               external-service connection (Slack, GitHub, Jira, ...)           ## Integrations
+INTEGRATION_HANDLERS      registry of available integration handlers                       ## Integrations
+LIVING_UI.md              per-project doc inside a Living UI project                       ## Living UI / ## File System
+Living UI                 generated React/HTML projects with persistent state              ## Living UI
+LLM                       large language model used for text generation                    ## Models
+LLMConsecutiveFailureError  circuit-breaker after 5 consecutive LLM failures               ## Errors / ## Models
+MCP                       Model Context Protocol; external tool servers                    ## MCP
+mcp_<server_name>         action set name registered when an MCP server connects           ## MCP / ## Action Sets
+memory_search             RAG action over indexed agent_file_system/ files                 ## Memory
+MemoryManager             ChromaDB-backed singleton for memory indexing + retrieval        ## Memory
+MEMORY.md                 distilled long-term memory; read via memory_search only          ## Memory / ## File System
+MISSION_INDEX_TEMPLATE.md template for workspace/missions/<name>/INDEX.md                  ## File System / ## Workspace
+mission                   multi-task initiative in workspace/missions/                     ## Workspace
+MODEL_REGISTRY            agent_core registry mapping providers to default models          ## Models
+onboarding                first-run setup flow (hard wizard + soft interview)              ## Onboarding Context
+outcome_history           per-task list of recent execution outcomes in PROACTIVE.md       ## Proactive
+parallelizable            decorator flag controlling whether action can run in parallel    ## Actions
+permission_tier           0-3 user-interaction level for proactive tasks                   PROACTIVE.md, ## Proactive
+PROACTIVE.md              recurring task definitions + Goals/Plan/Status                   ## Proactive / ## File System
+proactive task            task fired by a schedule, not a user prompt                      ## Proactive
+provider                  LLM provider name (openai, anthropic, gemini, ...)                ## Models
+react()                   the agent's main loop entry point                                 ## Runtime
+recurring_add             action to register a new recurring task in PROACTIVE.md          ## Proactive
+recurring_update_task     action to modify a task or record an outcome                     ## Proactive
+reinitialize_llm          internal call that rebuilds LLMInterface for a provider switch   ## Models
+schedule_task             action to add immediate / one-shot / recurring scheduled task    ## Proactive
+scheduler_config.json     cron schedules for system + user one-shot tasks                  ## Configs / ## Proactive
+simple task               <=3-action auto-ending task with no approval gate                 ## Tasks
+SKILL.md                  skill definition file with YAML frontmatter + body               ## Skills
+slow_mode                 settings.json flag throttling LLM requests                        ## Models
+SOUL.md                   personality file injected directly into system prompt            ## Self-Edit
+stream_edit               preferred action for editing existing files                      ## Files
+task_id                   unique identifier for a task; equals session_id                  ## Tasks / ## Runtime
+task_start                action to begin a task from conversation mode                    ## Tasks
+TASK_HISTORY.md           summaries of completed tasks (do not edit)                       ## File System
+task mode                 simple | complex; locked at task_start                            ## Tasks
+todo phase                Acknowledge / Collect / Execute / Verify / Confirm / Cleanup     ## Tasks
+trigger                   dispatch unit consumed by react()                                 ## Runtime
+USER.md                   user profile file (preferences, identity, goals)                  ## Self-Edit / ## File System
+VLM                       vision-language model used for image actions                      ## Models
+waiting_for_user_reply    task flag; trigger re-queues with 3-hour delay if no reply       ## Runtime / ## Tasks
+workflow                  one of 5 paths react() routes to                                  ## Runtime
+workflow lock             prevents concurrent memory / proactive runs                      ## Runtime
+workspace/                per-agent sandbox under agent_file_system/                        ## Workspace
+```
 
+If a term is missing, search the relevant section header (`grep_files "## <topic>" agent_file_system/AGENT.md`). If you encounter a new term that should be in this glossary, add it via the `## Self-Edit` AGENT.md flow.
diff --git a/agent_file_system/MEMORY.md b/agent_file_system/MEMORY.md
index e5e37224..96be4143 100644
--- a/agent_file_system/MEMORY.md
+++ b/agent_file_system/MEMORY.md
@@ -9,6 +9,3 @@ DO NOT copy and paste events here: This memory file only stores distilled memory
 
 ## Memory
 
-[2026-03-26 13:20:40] [system_warning] Token usage reached 80% of maximum limit (6000000 tokens)
-[2026-03-26 13:22:25] [system_limit] Task cancelled due to reaching maximum token limit (6000000 tokens)
-
diff --git a/agent_file_system/PROACTIVE.md b/agent_file_system/PROACTIVE.md
index c3706ac2..d7238f8b 100644
--- a/agent_file_system/PROACTIVE.md
+++ b/agent_file_system/PROACTIVE.md
@@ -1,6 +1,6 @@
 ---
 version: "1.0"
-last_updated: 2026-03-27T22:00:00Z  # Auto-updated by system (format: YYYY-MM-DDTHH:MM:SSZ)
+last_updated: null  # Auto-updated by system (format: YYYY-MM-DDTHH:MM:SSZ)
 ---
 
 # Proactive Tasks
@@ -178,20 +178,15 @@ No long-term goals defined yet.
 
 ### Current Focus
 <!-- Updated by week/day planner -->
-Supporting Living UI development projects and maintaining development workflow efficiency.
+No current focus defined.
 
 ### Recent Accomplishments
 <!-- Updated by planners after task completion -->
-- ✅ Successfully completed Living UI Todo Manager project with full kanban board functionality
-- ✅ Implemented persistent data storage with SQLite backend
-- ✅ Created responsive UI with drag-and-drop capabilities and modern design
+None yet.
 
 ### Upcoming Priorities
 <!-- Updated by day planner -->
-- Monitor Living UI project health and performance metrics
-- Proactively identify opportunities for new Living UI applications
-- Maintain development environment and dependencies
-- Track project completion rates and user satisfaction
+None defined.
 
 ---
 
diff --git a/app/agent_base.py b/app/agent_base.py
index 3ffbfe4f..ee3df6a0 100644
--- a/app/agent_base.py
+++ b/app/agent_base.py
@@ -30,33 +30,51 @@
 import uuid
 import json
 from dataclasses import dataclass
-from typing import Any, Awaitable, Callable, Dict, List, Optional, TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from agent_core import Action
+from typing import Any, Awaitable, Callable, Dict, List, Optional
 
 from agent_core import ActionLibrary, ActionManager, ActionRouter
 from agent_core import settings_manager, config_watcher
 
 from app.config import (
-    AGENT_WORKSPACE_ROOT,
     AGENT_FILE_SYSTEM_PATH,
     AGENT_FILE_SYSTEM_TEMPLATE_PATH,
     AGENT_MEMORY_CHROMA_PATH,
     PROCESS_MEMORY_AT_STARTUP,
+    PROJECT_ROOT,
+    GOOGLE_CLIENT_ID,
+    GOOGLE_CLIENT_SECRET,
+    OUTLOOK_CLIENT_ID,
+    LINKEDIN_CLIENT_ID,
+    LINKEDIN_CLIENT_SECRET,
+    NOTION_SHARED_CLIENT_ID,
+    NOTION_SHARED_CLIENT_SECRET,
+    SLACK_SHARED_CLIENT_ID,
+    SLACK_SHARED_CLIENT_SECRET,
+    TELEGRAM_SHARED_BOT_TOKEN,
+    TELEGRAM_SHARED_BOT_USERNAME,
+    TELEGRAM_API_ID,
+    TELEGRAM_API_HASH,
     get_api_key,
     get_base_url,
 )
+from craftos_integrations import (
+    configure as _configure_integrations,
+    initialize_manager,
+)
 
 from app.internal_action_interface import InternalActionInterface
+
 from app.llm import LLMInterface, LLMCallType
-from agent_core.core.impl.llm.errors import classify_llm_error, LLMConsecutiveFailureError
+from agent_core.core.impl.llm.errors import (
+    classify_llm_error,
+    classify_llm_error_message,
+    LLMConsecutiveFailureError,
+)
 from app.vlm_interface import VLMInterface
 from app.database_interface import DatabaseInterface
 from app.logger import logger
 from agent_core import (
     MemoryManager,
-    MemoryPointer,
     MemoryFileWatcher,
     create_memory_processing_task,
     WorkflowLockManager,
@@ -73,7 +91,7 @@
 from app.gui.gui_module import GUIModule
 from app.gui.handler import GUIHandler
 from app.scheduler import SchedulerManager
-from app.proactive import initialize_proactive_manager, get_proactive_manager
+from app.proactive import initialize_proactive_manager
 from app.ui_layer.settings.memory_settings import (
     is_memory_enabled,
     _parse_memory_items,
@@ -88,7 +106,6 @@
     EventStreamManagerRegistry,
     StateManagerRegistry,
     ContextEngineRegistry,
-    ActionExecutorRegistry,
     ActionManagerRegistry,
     TaskManagerRegistry,
     MemoryRegistry,
@@ -1297,26 +1314,49 @@ async def _handle_react_error(
         if not session_to_use or not self.event_stream_manager:
             return
 
-        # Get user-friendly error message
-        user_message = classify_llm_error(error)
-
-        # Fatal LLM errors must not re-queue the task - that causes infinite retry loops
-        # Walk the full exception chain (__cause__, __context__) to detect wrapped errors
+        # Walk the exception chain (__cause__, __context__) to detect the
+        # fatal-LLM case. We need the LLMConsecutiveFailureError to surface
+        # the *cause* of the 5 failures (e.g. "rate-limited on Google AI
+        # Studio"), not the meta-message about retry counts.
         is_fatal_llm_error = False
+        fatal_exc: LLMConsecutiveFailureError | None = None
+        seen: set[int] = set()
         exc: BaseException | None = error
-        while exc is not None:
+        while exc is not None and id(exc) not in seen:
+            seen.add(id(exc))
             if isinstance(exc, LLMConsecutiveFailureError):
                 is_fatal_llm_error = True
+                fatal_exc = exc
                 break
-            exc = exc.__cause__ or exc.__context__
-            if exc is error:  # prevent infinite loop on circular chains
+            cause = exc.__cause__ or exc.__context__
+            if cause is None or cause is exc:
                 break
+            exc = cause
+
+        # Compose the user-facing message. For the fatal case we lead with
+        # the cause (already a rich detailed string from the classifier)
+        # and prefix the abort context. For non-fatal cases the RuntimeError
+        # we receive was already constructed from `info.message` upstream
+        # in interface.py, so str(error) IS the rich text — classify is a
+        # no-op fallthrough that returns the same string back.
+        if is_fatal_llm_error and fatal_exc is not None and fatal_exc.last_error_info is not None:
+            cause_msg = fatal_exc.last_error_info.message
+            user_message = f"Aborted after consecutive failures. {cause_msg}"
+        elif is_fatal_llm_error and fatal_exc is not None:
+            # Old code path that didn't attach last_error_info — fall back
+            # to the wrapper's str(). Better than empty.
+            user_message = str(fatal_exc)
+        else:
+            try:
+                user_message = classify_llm_error_message(error)
+            except Exception:
+                user_message = str(error) or "AI service error"
 
         try:
             logger.debug("[REACT ERROR] Logging to event stream")
             self.event_stream_manager.log(
                 "error",
-                f"[REACT] {type(error).__name__}: {error}\n{tb}",
+                f"[REACT] {type(error).__name__}: {user_message}",
                 display_message=user_message,
                 task_id=session_to_use,
             )
@@ -1364,12 +1404,13 @@ def _cleanup_session(self) -> None:
     # ----- Agent Limits -----
 
     async def _check_agent_limits(self) -> bool:
-        agent_properties = STATE.get_agent_properties()
+        from app.state.agent_state import get_session_props
+        current_task_id: str = STATE.get_agent_property("current_task_id", "")
+        agent_properties = get_session_props(current_task_id).to_dict()
         action_count: int = agent_properties.get("action_count", 0)
         max_actions: int = agent_properties.get("max_actions_per_task", 0)
         token_count: int = agent_properties.get("token_count", 0)
         max_tokens: int = agent_properties.get("max_tokens_per_task", 0)
-        current_task_id: str = agent_properties.get("current_task_id", "")
 
         # Check action limits
         if (action_count / max_actions) >= 1.0:
@@ -1535,13 +1576,9 @@ async def handle_limit_continue(self, session_id: str) -> None:
             logger.warning(f"[LIMIT] Task {session_id} not found for limit continue")
             return
 
-        # Reset counters
-        STATE.set_agent_property("action_count", 0)
-        STATE.set_agent_property("token_count", 0)
-
-        # Also reset on the StateSession for this session
+        # Reset per-task counters on this session's StateSession.
         from agent_core.core.state.session import StateSession
-        session = StateSession.get(session_id)
+        session = StateSession.get_or_none(session_id)
         if session:
             session.agent_properties.set_property("action_count", 0)
             session.agent_properties.set_property("token_count", 0)
@@ -2118,21 +2155,36 @@ async def _create_new_session_trigger(
     async def _handle_chat_message(self, payload: Dict):
         """Decide where an incoming chat message goes.
 
-        Layered routing rules (deterministic first, LLM only as last resort):
-          1. Third-party external (no is_self_message): post notification, done.
-          2. UI reply with valid target_session_id: fire that session.
-          3. UI reply marker without valid target: new session, reply context
-             stays embedded in the message text.
-          4. Exactly one task is waiting_for_user_reply: fire that one.
-          5. Active tasks exist and message is genuinely ambiguous: routing LLM
-             with conservative prompt (defaults to new session). Handles Living
-             UI cross-references — chat is global, so a message about Living UI
-             B while viewing Living UI A should still route to B's task.
-          6. Default: new session.
-
-        Routing only decides *where* the message goes. The new session's first
-        action-selection LLM still picks send_message / task_start(simple) /
-        task_start(complex) as appropriate.
+        Each chat message is delivered to exactly one destination: an existing
+        task session, or a fresh session. Routing tries the cheap deterministic
+        signals first and only consults the LLM router when none of them apply.
+
+          1. Third-party external message (someone other than the user sent it
+             on a connected platform): post a notification to the main stream
+             and stop. No session, no agent action.
+
+          2. The UI attached an explicit target_session_id (the user clicked
+             "reply" on a specific task's message): fire that session. If the
+             session no longer exists, fall through.
+
+          3. The message text carries the "[REPLYING TO PREVIOUS AGENT MESSAGE]:"
+             marker but no valid target session: open a new session. The reply
+             context is already embedded in the message body.
+
+          4. At least one task is active: ask the routing LLM whether this
+             message clearly continues, modifies, cancels, or answers one of
+             them. The LLM sees each session's instruction, todo progress,
+             recent activity, waiting_for_user_reply status, and Living UI
+             binding, and defaults to "new" when in doubt. Living UI
+             cross-references are resolved here too — chat is global, so a
+             message about Living UI B while viewing Living UI A still routes
+             to B's task.
+
+          5. No active tasks (or the LLM chose "new"): open a new session.
+
+        Routing only decides *where* the message goes. Once it lands, the
+        target session's own action-selection LLM picks the next action
+        (send_message, task_start, task_update_todos, etc.).
         """
         try:
             chat_content = payload.get("text", "")
@@ -2178,24 +2230,13 @@ async def _handle_chat_message(self, payload: Dict):
                 await self._create_new_session_trigger(chat_content, payload, platform, gui_mode)
                 return
 
-            # ── Rule 4: Exactly one task is waiting_for_user_reply.
-            waiting_session_ids = []
-            if self.task_manager:
-                for tid in active_task_ids:
-                    task = self.task_manager.tasks.get(tid)
-                    if task and getattr(task, "waiting_for_user_reply", False):
-                        waiting_session_ids.append(tid)
-            if len(waiting_session_ids) == 1:
-                sid = waiting_session_ids[0]
-                logger.info(f"[CHAT] Routing to single waiting session {sid}")
-                if await self._fire_session(sid, chat_content, platform, living_ui_id):
-                    return
-
-            # ── Rule 5: Active tasks exist and signal is ambiguous → conservative routing LLM.
-            # Also handles Living UI cross-references: chat is global, so a message
-            # explicitly about Living UI B while viewing Living UI A should still
-            # route to B's task. The LLM sees each session's Living UI binding and
-            # the user's current Living UI to decide.
+            # ── Rule 4: Active tasks exist → conservative routing LLM.
+            # The LLM sees each session's waiting_for_user_reply status, Living UI
+            # binding, and recent activity, and defaults to "new" when in doubt.
+            # We intentionally do NOT short-circuit on "single waiting task":
+            # tasks often park on a final "anything else?" question, and the
+            # next user message may be a completely unrelated request that
+            # deserves its own session.
             if active_task_ids:
                 active_triggers = await self.triggers.list_triggers()
                 existing_sessions = self._format_sessions_for_routing(active_task_ids, active_triggers)
@@ -2218,7 +2259,7 @@ async def _handle_chat_message(self, payload: Dict):
                             return
                         logger.warning(f"[CHAT] LLM routed to {matched} but trigger not found — creating new session")
 
-            # ── Rule 6: Default — create a new session.
+            # ── Rule 5: Default — create a new session.
             await self._create_new_session_trigger(chat_content, payload, platform, gui_mode)
 
         except Exception as e:
@@ -3047,10 +3088,24 @@ async def _initialize_config_watcher(self) -> None:
                 from app.skill import skill_manager
 
                 async def _reload_skills_and_sync():
-                    """Reload skills and sync skill slash commands."""
+                    """Reload skills, sync slash commands, and broadcast the
+                    refreshed skill list so the Settings page UI updates
+                    without a manual reload."""
                     result = await skill_manager.reload()
                     if self.ui_controller:
                         self.ui_controller.sync_skill_commands()
+                        # Broadcast the refreshed list to the active adapter
+                        # (e.g. browser) so any open Settings page sees the
+                        # new / re-enabled skill immediately.
+                        adapter = getattr(self.ui_controller, "_adapter", None)
+                        broadcast_handler = getattr(adapter, "_handle_skill_list", None)
+                        if broadcast_handler is not None:
+                            try:
+                                await broadcast_handler()
+                            except Exception as e:
+                                logger.debug(
+                                    f"[SKILLS] Failed to broadcast skill list update: {e}"
+                                )
                     return result
 
                 config_watcher.register(
@@ -3059,12 +3114,6 @@ async def _reload_skills_and_sync():
                     name="skills_config.json"
                 )
 
-            # Register external_comms_config.json
-            external_comms_config_path = PROJECT_ROOT / "app" / "config" / "external_comms_config.json"
-            if external_comms_config_path.exists():
-                # We'll register this after external_comms is initialized
-                self._external_comms_config_path = external_comms_config_path
-
             # Start the config watcher
             config_watcher.start(event_loop)
             logger.info("[CONFIG_WATCHER] Config hot-reload initialized")
@@ -3079,64 +3128,101 @@ async def _reload_skills_and_sync():
     # =====================================
 
     async def _initialize_external_libraries(self) -> None:
-        """Import all platform modules so their @register_client decorators fire."""
+        """Configure craftos_integrations and start the external-comms manager.
+
+        Wires host config (project_root, OAuth env vars, agent name, OPENAI_API_KEY)
+        and boots the listener manager. ``initialize_manager()`` calls
+        ``autoload_integrations()`` internally during startup, so every integration's
+        @register_client / @register_handler decorators fire as a side-effect.
+        """
         try:
-            from app.external_comms.manager import _import_all_platforms
-            _import_all_platforms()
-            logger.info("[EXT LIBS] External platform modules loaded")
-        except Exception as e:
-            logger.warning(f"[EXT LIBS] Failed to load platform modules: {e}")
+            from app.onboarding import onboarding_manager
+            agent_name = onboarding_manager.state.agent_name or "CraftBot"
+        except Exception:
+            agent_name = "CraftBot"
+        _configure_integrations(
+            project_root=Path(PROJECT_ROOT),
+            logger=logger,
+            oauth={
+                # Google Workspace (Gmail / Calendar / Drive)
+                "GOOGLE_CLIENT_ID":            GOOGLE_CLIENT_ID,
+                "GOOGLE_CLIENT_SECRET":        GOOGLE_CLIENT_SECRET,
+                # Outlook (Microsoft Graph)
+                "OUTLOOK_CLIENT_ID":           OUTLOOK_CLIENT_ID,
+                # LinkedIn
+                "LINKEDIN_CLIENT_ID":          LINKEDIN_CLIENT_ID,
+                "LINKEDIN_CLIENT_SECRET":      LINKEDIN_CLIENT_SECRET,
+                # Notion (only used by the `invite` OAuth path; raw-token login needs nothing)
+                "NOTION_SHARED_CLIENT_ID":     NOTION_SHARED_CLIENT_ID,
+                "NOTION_SHARED_CLIENT_SECRET": NOTION_SHARED_CLIENT_SECRET,
+                # Slack (only used by the `invite` OAuth path)
+                "SLACK_SHARED_CLIENT_ID":      SLACK_SHARED_CLIENT_ID,
+                "SLACK_SHARED_CLIENT_SECRET":  SLACK_SHARED_CLIENT_SECRET,
+                # Telegram bot (shared-bot `invite` flow)
+                "TELEGRAM_SHARED_BOT_TOKEN":    TELEGRAM_SHARED_BOT_TOKEN,
+                "TELEGRAM_SHARED_BOT_USERNAME": TELEGRAM_SHARED_BOT_USERNAME,
+                # Telegram user (MTProto)
+                "TELEGRAM_API_ID":             TELEGRAM_API_ID,
+                "TELEGRAM_API_HASH":           TELEGRAM_API_HASH,
+            },
+            extras={"agent_name": agent_name, "openai_api_key": os.environ.get("OPENAI_API_KEY", "")},
+        )
+        self._external_comms = await initialize_manager(on_message=self._handle_external_event)
+        logger.info("[EXT LIBS] External integrations configured + manager started")
 
     # =====================================
     # Lifecycle
     # =====================================
 
-    async def run(
-        self,
-        *,
-        provider: str | None = None,
-        api_key: str = "",
-        base_url: str | None = None,
-        interface_mode: str = "tui",
-    ) -> None:
-        """
-        Launch the interactive loop for the agent.
+    async def boot(self, *, browser_ui, verbose: bool = True) -> None:
+        """Run the full production startup sequence except the UI loop.
+
+        Called from ``run()`` before the interactive interface starts.
+        Also called directly by the e2e test harness so tests get the
+        exact same setup as production without blocking on ``TUI/CLI/Browser``
+        interactive loops.
+
+        Steps:
+          1. Config watcher (hot-reload of settings.json)
+          2. MCP client + tool registration
+          3. Skills system
+          4. Usage reporter background flush
+          5. Integration manager (whatsapp_web, gmail, slack, etc.)
+          6. Optional memory processing on startup
+          7. Scheduler initialization + start
+          8. Resume triggers for tasks restored from previous session
 
         Args:
-            provider: Optional provider override passed to the interface before
-                chat starts; defaults to the provider configured during
-                initialization.
-            api_key: Optional API key presented in the interface for convenience.
-            base_url: Optional base URL for the provider.
-            interface_mode: "tui" for Textual interface, "cli" for command line.
+            verbose: When True, print human-readable per-step progress
+                (the same format ``app/main.py`` shows on app launch).
+                Tests pass False to keep output clean.
         """
-        # Check if browser startup UI is active
-        browser_ui = os.getenv("BROWSER_STARTUP_UI", "0") == "1"
 
-        def print_startup_step(step: int, total: int, message: str):
-            """Print a startup step in the appropriate format."""
+        def step(step_num: int, total: int, message: str) -> None:
+            if not verbose:
+                return
             if browser_ui:
                 # Browser mode: formatted with alignment and checkmark
-                prefix = f"  [{step:>2}/{total}]"
+                prefix = f"  [{step_num:>2}/{total}]"
                 step_width = 45
                 padded_msg = f"{message}...".ljust(step_width - len(prefix))
                 print(f"{prefix} {padded_msg}✓", flush=True)
             else:
                 # CLI mode: simple format
-                print(f"[{step}/{total}] {message}...")
+                print(f"[{step_num}/{total}] {message}...")
 
         # Startup progress messages
-        print_startup_step(3, 8, "Initializing agent")
+        step(3, 7, "Initializing agent")
 
         # Initialize settings manager and config watcher for hot-reload
         await self._initialize_config_watcher()
 
         # Initialize MCP client and register tools
-        print_startup_step(4, 8, "Connecting to MCP servers")
+        step(4, 7, "Connecting to MCP servers")
         await self._initialize_mcp()
 
         # Initialize skills system
-        print_startup_step(5, 8, "Loading skills")
+        step(5, 7, "Loading skills")
         await self._initialize_skills()
 
         # Start usage reporter background flush
@@ -3144,8 +3230,8 @@ def print_startup_step(step: int, total: int, message: str):
         self._usage_reporter = get_usage_reporter()
         self._usage_reporter.start_background_flush()
 
-        # Initialize external app libraries
-        print_startup_step(6, 8, "Loading libraries")
+        # Configure integrations + start external comms manager
+        step(6, 7, "Initializing integrations")
         await self._initialize_external_libraries()
 
         # Process unprocessed events into memory at startup (if enabled)
@@ -3153,8 +3239,7 @@ def print_startup_step(step: int, total: int, message: str):
             await self._process_memory_at_startup()
 
         # Initialize and start the scheduler (handles memory processing and other periodic tasks)
-        print_startup_step(7, 8, "Starting scheduler")
-        from app.config import PROJECT_ROOT
+        step(7, 7, "Starting scheduler")
         scheduler_config_path = PROJECT_ROOT / "app" / "config" / "scheduler_config.json"
         await self.scheduler.initialize(
             config_path=scheduler_config_path,
@@ -3172,20 +3257,31 @@ def print_startup_step(step: int, total: int, message: str):
         # Resume triggers for tasks restored from previous session
         await self._schedule_restored_task_triggers()
 
-        # Initialize external communications (WhatsApp, Telegram)
-        print_startup_step(8, 8, "Starting communications")
-        from app.external_comms import ExternalCommsManager
-        from app.external_comms.manager import initialize_manager
-        self._external_comms = initialize_manager(self)
-        await self._external_comms.start()
+    async def run(
+        self,
+        *,
+        provider: str | None = None,
+        api_key: str = "",
+        base_url: str | None = None,
+        interface_mode: str = "tui",
+    ) -> None:
+        """
+        Launch the interactive loop for the agent.
 
-        # Register external_comms config for hot-reload (after manager is initialized)
-        if hasattr(self, "_external_comms_config_path") and self._external_comms_config_path:
-            config_watcher.register(
-                self._external_comms_config_path,
-                self._external_comms.reload,
-                name="external_comms_config.json"
-            )
+        Performs the full production startup via ``boot()``, then enters
+        the chosen interactive interface.
+
+        Args:
+            provider: Optional provider override passed to the interface before
+                chat starts; defaults to the provider configured during
+                initialization.
+            api_key: Optional API key presented in the interface for convenience.
+            base_url: Optional base URL for the provider.
+            interface_mode: "tui" for Textual interface, "cli" for command line.
+        """
+        browser_ui = os.getenv("BROWSER_STARTUP_UI", "0") == "1"
+
+        await self.boot(browser_ui=browser_ui)
 
         # Startup complete (only print in CLI mode, browser mode handles this in run.py)
         if not browser_ui:
diff --git a/app/config.py b/app/config.py
index e8290284..e28fbaa6 100644
--- a/app/config.py
+++ b/app/config.py
@@ -100,12 +100,14 @@ def _get_default_settings() -> Dict[str, Any]:
             "anthropic": "",
             "google": "",
             "byteplus": "",
+            "openrouter": "",
         },
         "endpoints": {
             "remote_model_url": "",
             "byteplus_base_url": "https://ark.ap-southeast.bytepluses.com/api/v3",
             "google_api_base": "",
             "google_api_version": "",
+            "openrouter_base_url": "",
         },
         "web_search": {
             "google_cse_id": "",
@@ -221,6 +223,7 @@ def get_api_key(provider: str) -> str:
         "gemini": "google",
         "google": "google",
         "byteplus": "byteplus",
+        "openrouter": "openrouter",
     }
 
     settings_key = key_map.get(provider, provider)
@@ -247,6 +250,9 @@ def get_base_url(provider: str) -> Optional[str]:
         return url if url else "http://localhost:11434"
     elif provider == "gemini" or provider == "google":
         return endpoints.get("google_api_base") or None
+    elif provider == "openrouter":
+        url = endpoints.get("openrouter_base_url", "")
+        return url if url else "https://openrouter.ai/api/v1"
 
     return None
 
diff --git a/app/config/connection_test_models.json b/app/config/connection_test_models.json
index d18b0783..70bb41b8 100644
--- a/app/config/connection_test_models.json
+++ b/app/config/connection_test_models.json
@@ -20,7 +20,7 @@
         "model": "MiniMax-Text-01"
     },
     "moonshot": {
-        "model": "moonshot-v1-8k"
+        "model": "kimi-k2.5"
     },
     "remote": {
         "model": "llama3"
diff --git a/app/config/mcp_config.json b/app/config/mcp_config.json
index d9040e06..f77b823f 100644
--- a/app/config/mcp_config.json
+++ b/app/config/mcp_config.json
@@ -1262,7 +1262,7 @@
         "AMADEUS_API_KEY": "",
         "AMADEUS_API_SECRET": ""
       },
-      "enabled": true
+      "enabled": false
     },
     {
       "name": "booking-mcp",
diff --git a/app/config/settings.json b/app/config/settings.json
index 12c00359..9be5089a 100644
--- a/app/config/settings.json
+++ b/app/config/settings.json
@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
+  "version": "1.3.1",
   "general": {
     "agent_name": "CraftBot",
     "os_language": "en"
@@ -14,10 +14,10 @@
     "item_word_limit": 150
   },
   "model": {
-    "llm_provider": "byteplus",
-    "vlm_provider": "byteplus",
-    "llm_model": "kimi-k2-250905",
-    "vlm_model": "seed-1-6-250915",
+    "llm_provider": "anthropic",
+    "vlm_provider": "anthropic",
+    "llm_model": "claude-sonnet-4-5-20250929",
+    "vlm_model": "claude-sonnet-4-5-20250929",
     "slow_mode": true,
     "slow_mode_tpm_limit": 25000
   },
@@ -25,14 +25,16 @@
     "openai": "",
     "anthropic": "",
     "google": "",
-    "byteplus": ""
+    "byteplus": "",
+    "openrouter": ""
   },
   "endpoints": {
     "remote_model_url": "",
     "byteplus_base_url": "https://ark.ap-southeast.bytepluses.com/api/v3",
     "google_api_base": "",
     "google_api_version": "",
-    "remote": "http://localhost:11434"
+    "remote": "http://localhost:11434",
+    "openrouter_base_url": ""
   },
   "gui": {
     "enabled": true,
@@ -76,6 +78,7 @@
     "openai": false,
     "anthropic": false,
     "google": true,
-    "byteplus": true
+    "byteplus": true,
+    "openrouter": false
   }
 }
\ No newline at end of file
diff --git a/app/config/skills_config.json b/app/config/skills_config.json
index 5f963ad8..203b0611 100644
--- a/app/config/skills_config.json
+++ b/app/config/skills_config.json
@@ -9,7 +9,9 @@
     "xlsx",
     "living-ui-creator",
     "living-ui-manager",
-    "living-ui-modify"
+    "living-ui-modify",
+    "craftbot-skill-creator",
+    "craftbot-skill-improve"
   ],
   "disabled_skills": [
     "cli-anything",
diff --git a/app/credentials/__init__.py b/app/credentials/__init__.py
deleted file mode 100644
index 8f21c90e..00000000
--- a/app/credentials/__init__.py
+++ /dev/null
@@ -1,29 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Credentials module - re-exports from agent_core plus project-specific handlers."""
-
-# Re-export from agent_core
-from agent_core import (
-    get_credential,
-    get_credentials,
-    has_embedded_credentials,
-    run_oauth_flow,
-)
-
-# Project-specific
-from .handlers import (
-    IntegrationHandler,
-    INTEGRATION_HANDLERS,
-    LOCAL_USER_ID,
-)
-
-__all__ = [
-    # From agent_core
-    "get_credential",
-    "get_credentials",
-    "has_embedded_credentials",
-    "run_oauth_flow",
-    # Project-specific handlers
-    "IntegrationHandler",
-    "INTEGRATION_HANDLERS",
-    "LOCAL_USER_ID",
-]
diff --git a/app/credentials/handlers.py b/app/credentials/handlers.py
deleted file mode 100644
index 830c2b07..00000000
--- a/app/credentials/handlers.py
+++ /dev/null
@@ -1,1165 +0,0 @@
-"""All integration credential handlers + registry."""
-from __future__ import annotations
-
-
-import base64
-import hashlib
-import logging
-import secrets
-import time
-import webbrowser
-from abc import ABC, abstractmethod
-from typing import Tuple
-from urllib.parse import urlencode
-
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-
-logger = logging.getLogger(__name__)
-
-LOCAL_USER_ID = "local"
-REDIRECT_URI = "http://localhost:8765"
-REDIRECT_URI_HTTPS = "https://localhost:8765"  # For providers that require HTTPS (e.g. Slack)
-
-# Pending Telegram MTProto auth state: {phone_number: {phone_code_hash, session_string, api_id, api_hash}}
-_pending_telegram_auth: dict[str, dict] = {}
-
-
-class IntegrationHandler(ABC):
-    @abstractmethod
-    async def login(self, args: list[str]) -> Tuple[bool, str]: ...
-    @abstractmethod
-    async def logout(self, args: list[str]) -> Tuple[bool, str]: ...
-    @abstractmethod
-    async def status(self) -> Tuple[bool, str]: ...
-
-    async def invite(self, args: list[str]) -> Tuple[bool, str]:
-        return False, "Invite not available for this integration. Use 'login' instead."
-
-    @property
-    def subcommands(self) -> list[str]:
-        return ["login", "logout", "status"]
-
-    async def handle(self, sub: str, args: list[str]) -> Tuple[bool, str]:
-        """Route subcommand. Override in subclasses for extra subcommands."""
-        if sub == "invite":    return await self.invite(args)
-        if sub == "login":     return await self.login(args)
-        if sub == "logout":    return await self.logout(args)
-        if sub == "status":    return await self.status()
-        return False, f"Unknown subcommand: {sub}. Use: {', '.join(self.subcommands)}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Google
-# ═══════════════════════════════════════════════════════════════════
-
-class GoogleHandler(IntegrationHandler):
-    SCOPES = "https://www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/contacts.readonly https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/youtube.readonly https://www.googleapis.com/auth/youtube.force-ssl"
-
-    async def login(self, args):
-        from app.config import GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
-        if not GOOGLE_CLIENT_ID:
-            return False, "Not configured. Set GOOGLE_CLIENT_ID env var (or use embedded credentials)."
-
-        # Generate PKCE code_verifier and code_challenge (RFC 7636)
-        code_verifier = secrets.token_urlsafe(64)[:128]
-        code_challenge = base64.urlsafe_b64encode(
-            hashlib.sha256(code_verifier.encode()).digest()
-        ).decode().rstrip("=")
-
-        params = {
-            "client_id": GOOGLE_CLIENT_ID,
-            "redirect_uri": REDIRECT_URI,
-            "response_type": "code",
-            "scope": self.SCOPES,
-            "access_type": "offline",
-            "prompt": "consent",
-            "state": secrets.token_urlsafe(32),
-            "code_challenge": code_challenge,
-            "code_challenge_method": "S256",
-        }
-        from agent_core import run_oauth_flow_async
-        code, error = await run_oauth_flow_async(f"https://accounts.google.com/o/oauth2/v2/auth?{urlencode(params)}")
-        if error: return False, f"Google OAuth failed: {error}"
-
-        token_data = {
-            "code": code,
-            "client_id": GOOGLE_CLIENT_ID,
-            "redirect_uri": REDIRECT_URI,
-            "grant_type": "authorization_code",
-            "code_verifier": code_verifier,
-        }
-        if GOOGLE_CLIENT_SECRET:
-            token_data["client_secret"] = GOOGLE_CLIENT_SECRET
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.post("https://oauth2.googleapis.com/token", data=token_data) as r:
-                if r.status != 200: return False, f"Token exchange failed: {await r.text()}"
-                tokens = await r.json()
-            async with s.get("https://www.googleapis.com/oauth2/v2/userinfo", headers={"Authorization": f"Bearer {tokens['access_token']}"}) as r:
-                if r.status != 200: return False, "Failed to fetch user info."
-                info = await r.json()
-
-        from app.external_comms.platforms.google_workspace import GoogleCredential
-        save_credential("google.json", GoogleCredential(
-            access_token=tokens["access_token"],
-            refresh_token=tokens.get("refresh_token", ""),
-            token_expiry=time.time() + tokens.get("expires_in", 3600),
-            client_id=GOOGLE_CLIENT_ID,
-            client_secret=GOOGLE_CLIENT_SECRET,
-            email=info.get("email", ""),
-        ))
-        return True, f"Google connected as {info.get('email')}"
-
-    async def logout(self, args):
-        if not has_credential("google.json"):
-            return False, "No Google credentials found."
-        remove_credential("google.json")
-        return True, "Removed Google credential."
-
-    async def status(self):
-        if not has_credential("google.json"):
-            return True, "Google: Not connected"
-        from app.external_comms.platforms.google_workspace import GoogleCredential
-        cred = load_credential("google.json", GoogleCredential)
-        email = cred.email if cred else "unknown"
-        return True, f"Google: Connected\n  - {email}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Slack
-# ═══════════════════════════════════════════════════════════════════
-
-class SlackHandler(IntegrationHandler):
-    @property
-    def subcommands(self) -> list[str]:
-        return ["invite", "login", "logout", "status"]
-
-    async def invite(self, args):
-        from app.config import SLACK_SHARED_CLIENT_ID, SLACK_SHARED_CLIENT_SECRET
-        if not SLACK_SHARED_CLIENT_ID or not SLACK_SHARED_CLIENT_SECRET:
-            return False, "CraftOS Slack app not configured. Set SLACK_SHARED_CLIENT_ID and SLACK_SHARED_CLIENT_SECRET env vars.\nAlternatively, use /slack login <bot_token> with your own Slack app."
-
-        scopes = "chat:write,channels:read,channels:history,groups:read,groups:history,users:read,files:write,im:read,im:write,im:history"
-        params = {"client_id": SLACK_SHARED_CLIENT_ID, "scope": scopes, "redirect_uri": REDIRECT_URI_HTTPS, "state": secrets.token_urlsafe(32)}
-        from agent_core import run_oauth_flow_async
-        code, error = await run_oauth_flow_async(f"https://slack.com/oauth/v2/authorize?{urlencode(params)}", use_https=True)
-        if error: return False, f"Slack OAuth failed: {error}"
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.post("https://slack.com/api/oauth.v2.access", data={"code": code, "client_id": SLACK_SHARED_CLIENT_ID, "client_secret": SLACK_SHARED_CLIENT_SECRET, "redirect_uri": REDIRECT_URI_HTTPS}) as r:
-                data = await r.json()
-                if not data.get("ok"): return False, f"Slack OAuth token exchange failed: {data.get('error')}"
-
-        bot_token = data.get("access_token", "")
-        team_id = data.get("team", {}).get("id", "")
-        team_name = data.get("team", {}).get("name", team_id)
-
-        from app.external_comms.platforms.slack import SlackCredential
-        save_credential("slack.json", SlackCredential(bot_token=bot_token, workspace_id=team_id, team_name=team_name))
-        return True, f"Slack connected via CraftOS app: {team_name} ({team_id})"
-
-    async def login(self, args):
-        if not args: return False, "Usage: /slack login <bot_token> [workspace_name]"
-        bot_token = args[0]
-        if not bot_token.startswith(("xoxb-", "xoxp-")): return False, "Invalid token. Expected xoxb-... or xoxp-..."
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.post("https://slack.com/api/auth.test", headers={"Authorization": f"Bearer {bot_token}"}) as r:
-                data = await r.json()
-                if not data.get("ok"): return False, f"Slack auth failed: {data.get('error')}"
-                team_id = data.get("team_id", "")
-                workspace_name = args[1] if len(args) > 1 else data.get("team", team_id)
-
-        from app.external_comms.platforms.slack import SlackCredential
-        save_credential("slack.json", SlackCredential(bot_token=bot_token, workspace_id=team_id, team_name=workspace_name))
-        return True, f"Slack connected: {workspace_name} ({team_id})"
-
-    async def logout(self, args):
-        if not has_credential("slack.json"):
-            return False, "No Slack credentials found."
-        remove_credential("slack.json")
-        return True, "Removed Slack credential."
-
-    async def status(self):
-        if not has_credential("slack.json"):
-            return True, "Slack: Not connected"
-        from app.external_comms.platforms.slack import SlackCredential
-        cred = load_credential("slack.json", SlackCredential)
-        name = cred.team_name or cred.workspace_id if cred else "unknown"
-        return True, f"Slack: Connected\n  - {name} ({cred.workspace_id})"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Notion
-# ═══════════════════════════════════════════════════════════════════
-
-class NotionHandler(IntegrationHandler):
-    @property
-    def subcommands(self) -> list[str]:
-        return ["invite", "login", "logout", "status"]
-
-    async def invite(self, args):
-        from app.config import NOTION_SHARED_CLIENT_ID, NOTION_SHARED_CLIENT_SECRET
-        if not NOTION_SHARED_CLIENT_ID or not NOTION_SHARED_CLIENT_SECRET:
-            return False, "CraftOS Notion integration not configured. Set NOTION_SHARED_CLIENT_ID and NOTION_SHARED_CLIENT_SECRET env vars.\nAlternatively, use /notion login <token> with your own integration token."
-
-        params = {"client_id": NOTION_SHARED_CLIENT_ID, "redirect_uri": REDIRECT_URI, "response_type": "code", "owner": "user", "state": secrets.token_urlsafe(32)}
-        from agent_core import run_oauth_flow_async
-        code, error = await run_oauth_flow_async(f"https://api.notion.com/v1/oauth/authorize?{urlencode(params)}")
-        if error: return False, f"Notion OAuth failed: {error}"
-
-        import aiohttp
-        basic = base64.b64encode(f"{NOTION_SHARED_CLIENT_ID}:{NOTION_SHARED_CLIENT_SECRET}".encode()).decode()
-        async with aiohttp.ClientSession() as s:
-            async with s.post("https://api.notion.com/v1/oauth/token",
-                              json={"grant_type": "authorization_code", "code": code, "redirect_uri": REDIRECT_URI},
-                              headers={"Authorization": f"Basic {basic}", "Content-Type": "application/json"}) as r:
-                if r.status != 200: return False, f"Notion token exchange failed: {await r.text()}"
-                data = await r.json()
-
-        token = data.get("access_token", "")
-        ws_name = data.get("workspace_name", "default")
-
-        from app.external_comms.platforms.notion import NotionCredential
-        save_credential("notion.json", NotionCredential(token=token))
-        return True, f"Notion connected via CraftOS integration: {ws_name}"
-
-    async def login(self, args):
-        if not args: return False, "Usage: /notion login <integration_token>"
-        token = args[0]
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.get("https://api.notion.com/v1/users/me", headers={"Authorization": f"Bearer {token}", "Notion-Version": "2022-06-28"}) as r:
-                if r.status != 200: return False, f"Notion auth failed: {r.status}"
-                data = await r.json()
-
-        ws_name = data.get("bot", {}).get("workspace_name", "default")
-        from app.external_comms.platforms.notion import NotionCredential
-        save_credential("notion.json", NotionCredential(token=token))
-        return True, f"Notion connected: {ws_name}"
-
-    async def logout(self, args):
-        if not has_credential("notion.json"):
-            return False, "No Notion credentials found."
-        remove_credential("notion.json")
-        return True, "Removed Notion credential."
-
-    async def status(self):
-        if not has_credential("notion.json"):
-            return True, "Notion: Not connected"
-        return True, "Notion: Connected"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# LinkedIn
-# ═══════════════════════════════════════════════════════════════════
-
-class LinkedInHandler(IntegrationHandler):
-    async def login(self, args):
-        from app.config import LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
-        if not LINKEDIN_CLIENT_ID or not LINKEDIN_CLIENT_SECRET:
-            return False, "Not configured. Set LINKEDIN_CLIENT_ID and LINKEDIN_CLIENT_SECRET env vars."
-
-        params = {"response_type": "code", "client_id": LINKEDIN_CLIENT_ID, "redirect_uri": REDIRECT_URI, "scope": "openid profile email w_member_social", "state": secrets.token_urlsafe(32)}
-        from agent_core import run_oauth_flow_async
-        code, error = await run_oauth_flow_async(f"https://www.linkedin.com/oauth/v2/authorization?{urlencode(params)}")
-        if error: return False, f"LinkedIn OAuth failed: {error}"
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.post("https://www.linkedin.com/oauth/v2/accessToken", data={"grant_type": "authorization_code", "code": code, "client_id": LINKEDIN_CLIENT_ID, "client_secret": LINKEDIN_CLIENT_SECRET, "redirect_uri": REDIRECT_URI}) as r:
-                if r.status != 200: return False, f"Token exchange failed: {await r.text()}"
-                tokens = await r.json()
-            async with s.get("https://api.linkedin.com/v2/userinfo", headers={"Authorization": f"Bearer {tokens['access_token']}"}) as r:
-                if r.status != 200: return False, "Failed to fetch user info."
-                info = await r.json()
-
-        from app.external_comms.platforms.linkedin import LinkedInCredential
-        save_credential("linkedin.json", LinkedInCredential(
-            access_token=tokens["access_token"],
-            refresh_token=tokens.get("refresh_token", ""),
-            token_expiry=time.time() + tokens.get("expires_in", 3600),
-            client_id=LINKEDIN_CLIENT_ID,
-            client_secret=LINKEDIN_CLIENT_SECRET,
-            linkedin_id=info.get("sub", ""),
-            user_id=info.get("sub", ""),
-        ))
-        return True, f"LinkedIn connected as {info.get('name')} ({info.get('email')})"
-
-    async def logout(self, args):
-        if not has_credential("linkedin.json"):
-            return False, "No LinkedIn credentials found."
-        remove_credential("linkedin.json")
-        return True, "Removed LinkedIn credential."
-
-    async def status(self):
-        if not has_credential("linkedin.json"):
-            return True, "LinkedIn: Not connected"
-        from app.external_comms.platforms.linkedin import LinkedInCredential
-        cred = load_credential("linkedin.json", LinkedInCredential)
-        lid = cred.linkedin_id if cred else "unknown"
-        return True, f"LinkedIn: Connected\n  - {lid}"
-
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Discord (bot token)
-# ═══════════════════════════════════════════════════════════════════
-
-class DiscordHandler(IntegrationHandler):
-    @property
-    def subcommands(self) -> list[str]:
-        return ["login", "logout", "status"]
-
-    async def login(self, args):
-        if not args: return False, "Usage: /discord login <bot_token>"
-        bot_token = args[0]
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.get("https://discord.com/api/v10/users/@me", headers={"Authorization": f"Bot {bot_token}"}) as r:
-                if r.status != 200: return False, f"Invalid bot token: {r.status}"
-                data = await r.json()
-
-        from app.external_comms.platforms.discord import DiscordCredential
-        save_credential("discord.json", DiscordCredential(bot_token=bot_token))
-        return True, f"Discord bot connected: {data.get('username')} ({data.get('id')})"
-
-    async def logout(self, args):
-        if not has_credential("discord.json"):
-            return False, "No Discord credentials found."
-        # Stop the active gateway listener before removing credentials
-        try:
-            from app.external_comms.manager import get_external_comms_manager
-            manager = get_external_comms_manager()
-            if manager:
-                await manager.stop_platform("discord")
-        except Exception:
-            pass
-        remove_credential("discord.json")
-        return True, "Removed Discord credential."
-
-    async def status(self):
-        if not has_credential("discord.json"):
-            return True, "Discord: Not connected"
-        from app.external_comms.platforms.discord import DiscordCredential
-        cred = load_credential("discord.json", DiscordCredential)
-        if not cred or not cred.bot_token:
-            return True, "Discord: Not connected"
-        return True, "Discord: Connected (bot token)"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Telegram (unified: invite + bot + user)
-# ═══════════════════════════════════════════════════════════════════
-
-class TelegramHandler(IntegrationHandler):
-    @property
-    def subcommands(self) -> list[str]:
-        return ["invite", "login", "login-user", "login-qr", "logout", "status"]
-
-    async def handle(self, sub, args):
-        if sub == "login-user": return await self._login_user(args)
-        if sub == "login-qr": return await self._login_qr(args)
-        return await super().handle(sub, args)
-
-    async def invite(self, args):
-        from app.config import TELEGRAM_SHARED_BOT_TOKEN, TELEGRAM_SHARED_BOT_USERNAME
-        if not TELEGRAM_SHARED_BOT_TOKEN or not TELEGRAM_SHARED_BOT_USERNAME:
-            return False, "CraftOS Telegram bot not configured. Set TELEGRAM_SHARED_BOT_TOKEN and TELEGRAM_SHARED_BOT_USERNAME env vars.\nAlternatively, use /telegram login <bot_token> with your own bot from @BotFather."
-
-        # Validate shared bot token
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.get(f"https://api.telegram.org/bot{TELEGRAM_SHARED_BOT_TOKEN}/getMe") as r:
-                data = await r.json()
-                if not data.get("ok"): return False, f"CraftOS Telegram bot token is invalid: {data.get('description')}"
-                info = data["result"]
-
-        from app.external_comms.platforms.telegram_bot import TelegramBotCredential
-        save_credential("telegram_bot.json", TelegramBotCredential(
-            bot_token=TELEGRAM_SHARED_BOT_TOKEN,
-            bot_username=info.get("username", ""),
-        ))
-
-        bot_link = f"https://t.me/{TELEGRAM_SHARED_BOT_USERNAME}"
-        webbrowser.open(bot_link)
-        return True, (
-            f"CraftOS Telegram bot connected: @{info.get('username')}\n"
-            f"Start chatting or add to groups: {bot_link}"
-        )
-
-    async def login(self, args):
-        if not args: return False, "Usage: /telegram login <bot_token>\nGet from @BotFather on Telegram."
-        bot_token = args[0]
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.get(f"https://api.telegram.org/bot{bot_token}/getMe") as r:
-                data = await r.json()
-                if not data.get("ok"): return False, f"Invalid bot token: {data.get('description')}"
-                info = data["result"]
-
-        from app.external_comms.platforms.telegram_bot import TelegramBotCredential
-        save_credential("telegram_bot.json", TelegramBotCredential(
-            bot_token=bot_token,
-            bot_username=info.get("username", ""),
-        ))
-        return True, f"Telegram bot connected: @{info.get('username')} ({info.get('id')})"
-
-    async def _login_user(self, args):
-        if not args:
-            return False, (
-                "Usage:\n"
-                "  Step 1: /telegram login-user <phone_number>\n"
-                "  Step 2: /telegram login-user <phone_number> <code> [2fa_password]\n\n"
-                "Requires TELEGRAM_API_ID and TELEGRAM_API_HASH env vars.\n"
-                "Get them from https://my.telegram.org"
-            )
-
-        phone = args[0]
-
-        from app.config import TELEGRAM_API_ID, TELEGRAM_API_HASH
-        if not TELEGRAM_API_ID or not TELEGRAM_API_HASH:
-            return False, (
-                "Not configured. Set TELEGRAM_API_ID and TELEGRAM_API_HASH env vars.\n"
-                "Get them from https://my.telegram.org → API development tools."
-            )
-
-        try:
-            api_id = int(TELEGRAM_API_ID)
-        except ValueError:
-            return False, "TELEGRAM_API_ID must be a number."
-
-        # Step 2: phone + code → complete auth
-        if len(args) >= 2:
-            code = args[1]
-            password = args[2] if len(args) > 2 else None
-
-            pending = _pending_telegram_auth.get(phone)
-            if not pending:
-                return False, f"No pending auth for {phone}. Run /telegram login-user {phone} first to send the code."
-
-            try:
-                from app.external_comms.platforms.telegram_mtproto_helpers import complete_auth
-            except ImportError:
-                return False, "Telethon not installed. Run: pip install telethon"
-
-            result = await complete_auth(
-                api_id=api_id,
-                api_hash=TELEGRAM_API_HASH,
-                phone_number=phone,
-                code=code,
-                phone_code_hash=pending["phone_code_hash"],
-                password=password,
-                pending_session_string=pending["session_string"],
-            )
-
-            if "error" in result:
-                details = result.get("details", {})
-                if details.get("status") == "2fa_required":
-                    return False, "Two-factor authentication is enabled.\nUsage: /telegram login-user <phone> <code> <2fa_password>"
-                if details.get("status") == "invalid_code":
-                    return False, "Invalid verification code. Try again with: /telegram login-user <phone> <code>"
-                if details.get("status") == "code_expired":
-                    _pending_telegram_auth.pop(phone, None)
-                    return False, "Code expired. Run /telegram login-user <phone> again to get a new code."
-                return False, f"Auth failed: {result['error']}"
-
-            # Success — store credential
-            auth = result["result"]
-            _pending_telegram_auth.pop(phone, None)
-
-            from app.external_comms.platforms.telegram_user import TelegramUserCredential
-            save_credential("telegram_user.json", TelegramUserCredential(
-                session_string=auth["session_string"],
-                api_id=str(api_id),
-                api_hash=TELEGRAM_API_HASH,
-                phone_number=auth.get("phone", phone),
-            ))
-
-            account_name = f"{auth.get('first_name', '')} {auth.get('last_name', '')}".strip()
-            username = f" (@{auth['username']})" if auth.get("username") else ""
-            return True, f"Telegram user connected: {account_name}{username}"
-
-        # Step 1: phone only → send OTP
-        try:
-            from app.external_comms.platforms.telegram_mtproto_helpers import start_auth
-        except ImportError:
-            return False, "Telethon not installed. Run: pip install telethon"
-
-        result = await start_auth(api_id=api_id, api_hash=TELEGRAM_API_HASH, phone_number=phone)
-
-        if "error" in result:
-            return False, f"Failed to send code: {result['error']}"
-
-        # Store pending auth state
-        _pending_telegram_auth[phone] = {
-            "phone_code_hash": result["result"]["phone_code_hash"],
-            "session_string": result["result"]["session_string"],
-        }
-
-        return True, (
-            f"Verification code sent to {phone}.\n"
-            f"Check your Telegram app (or SMS) for the code, then run:\n"
-            f"  /telegram login-user {phone} <code>"
-        )
-
-    async def _login_qr(self, args):
-        """Login to Telegram user account by scanning a QR code."""
-        logger.info("[Telegram QR] Starting QR login flow")
-        from app.config import TELEGRAM_API_ID, TELEGRAM_API_HASH
-        if not TELEGRAM_API_ID or not TELEGRAM_API_HASH:
-            logger.warning("[Telegram QR] Missing TELEGRAM_API_ID or TELEGRAM_API_HASH env vars")
-            return False, (
-                "Not configured. Set TELEGRAM_API_ID and TELEGRAM_API_HASH env vars.\n"
-                "Get them from https://my.telegram.org → API development tools."
-            )
-
-        try:
-            api_id = int(TELEGRAM_API_ID)
-        except ValueError:
-            return False, "TELEGRAM_API_ID must be a number."
-
-        try:
-            from app.external_comms.platforms.telegram_mtproto_helpers import qr_login
-        except ImportError:
-            logger.error("[Telegram QR] Telethon not installed")
-            return False, "Telethon not installed. Run: pip install telethon"
-
-        # Verify qrcode package is available before starting the flow
-        try:
-            import qrcode as _qrcode_check  # noqa: F401
-        except ImportError:
-            logger.error("[Telegram QR] qrcode package not installed")
-            return False, "qrcode package not installed. Run: pip install qrcode[pil]"
-
-        import tempfile, os
-
-        qr_file_path = None
-        qr_error = None
-
-        def on_qr_url(url: str):
-            """Generate QR code image and open it for the user to scan."""
-            nonlocal qr_file_path, qr_error
-            try:
-                import qrcode
-                qr = qrcode.QRCode(version=1, box_size=10, border=4)
-                qr.add_data(url)
-                qr.make(fit=True)
-                img = qr.make_image(fill_color="black", back_color="white")
-
-                qr_file_path = os.path.join(tempfile.gettempdir(), "telegram_qr_login.png")
-                img.save(qr_file_path)
-                logger.info(f"[Telegram QR] QR code saved to {qr_file_path}")
-
-                # Open the QR code image (prefer os.startfile on Windows)
-                import sys
-                if sys.platform == "win32":
-                    os.startfile(qr_file_path)
-                else:
-                    webbrowser.open(f"file://{qr_file_path}")
-                logger.info("[Telegram QR] QR code opened")
-            except Exception as e:
-                qr_error = str(e)
-                logger.error(f"[Telegram QR] Failed to generate/open QR code: {e}")
-
-        logger.info("[Telegram QR] Calling qr_login...")
-        result = await qr_login(
-            api_id=api_id,
-            api_hash=TELEGRAM_API_HASH,
-            on_qr_url=on_qr_url,
-            timeout=120,
-        )
-        logger.info(f"[Telegram QR] qr_login returned: {'ok' if 'ok' in result else 'error'}")
-
-        # Clean up QR image
-        if qr_file_path and os.path.exists(qr_file_path):
-            try:
-                os.remove(qr_file_path)
-            except Exception:
-                pass
-
-        if "error" in result:
-            details = result.get("details", {})
-            if details.get("status") == "2fa_required":
-                # Save pending session for 2FA completion
-                session_str = details.get("session_string", "")
-                if session_str:
-                    _pending_telegram_auth["__qr_2fa__"] = {"session_string": session_str}
-                return False, (
-                    "QR scan succeeded but 2FA is enabled.\n"
-                    "Complete login with: /telegram login-user <phone> <code> <2fa_password>\n"
-                    "Or disable 2FA in Telegram settings and try again."
-                )
-            return False, f"QR login failed: {result['error']}"
-
-        # Success — store credential
-        auth = result["result"]
-        from app.external_comms.platforms.telegram_user import TelegramUserCredential
-        save_credential("telegram_user.json", TelegramUserCredential(
-            session_string=auth["session_string"],
-            api_id=str(api_id),
-            api_hash=TELEGRAM_API_HASH,
-            phone_number=auth.get("phone", ""),
-        ))
-
-        account_name = f"{auth.get('first_name', '')} {auth.get('last_name', '')}".strip()
-        username = f" (@{auth['username']})" if auth.get("username") else ""
-        return True, f"Telegram user linked: {account_name}{username}"
-
-    async def logout(self, args):
-        bot_exists = has_credential("telegram_bot.json")
-        user_exists = has_credential("telegram_user.json")
-
-        if not bot_exists and not user_exists:
-            return False, "No Telegram credentials found."
-
-        if args:
-            target = args[0].lower()
-            if target in ("bot", "bot_api"):
-                if bot_exists:
-                    remove_credential("telegram_bot.json")
-                    return True, "Removed Telegram bot credential."
-                return False, "No Telegram bot credential found."
-            elif target in ("user", "mtproto"):
-                if user_exists:
-                    remove_credential("telegram_user.json")
-                    return True, "Removed Telegram user credential."
-                return False, "No Telegram user credential found."
-            elif target == "all":
-                if bot_exists: remove_credential("telegram_bot.json")
-                if user_exists: remove_credential("telegram_user.json")
-                return True, "Removed all Telegram credentials."
-            else:
-                return False, f"Unknown Telegram credential target: {target}. Use 'bot' or 'user'."
-
-        # No args — remove all
-        if bot_exists: remove_credential("telegram_bot.json")
-        if user_exists: remove_credential("telegram_user.json")
-        return True, "Removed all Telegram credentials."
-
-    async def status(self):
-        bot_exists = has_credential("telegram_bot.json")
-        user_exists = has_credential("telegram_user.json")
-
-        if not bot_exists and not user_exists:
-            return True, "Telegram: Not connected"
-
-        lines = []
-        if bot_exists:
-            from app.external_comms.platforms.telegram_bot import TelegramBotCredential
-            cred = load_credential("telegram_bot.json", TelegramBotCredential)
-            bot_label = f"@{cred.bot_username}" if cred and cred.bot_username else "Bot configured"
-            lines.append(f"  - {bot_label} (bot)")
-        if user_exists:
-            from app.external_comms.platforms.telegram_user import TelegramUserCredential
-            cred = load_credential("telegram_user.json", TelegramUserCredential)
-            user_label = cred.phone_number if cred and cred.phone_number else "User configured"
-            lines.append(f"  - {user_label} (user)")
-
-        return True, "Telegram: Connected\n" + "\n".join(lines)
-
-
-# ═══════════════════════════════════════════════════════════════════
-# WhatsApp (unified: business + web)
-# ═══════════════════════════════════════════════════════════════════
-
-class WhatsAppHandler(IntegrationHandler):
-    @property
-    def subcommands(self) -> list[str]:
-        return ["login", "logout", "status"]
-
-    async def handle(self, sub, args):
-        if sub == "login": return await self._login_web(args)
-        return await super().handle(sub, args)
-
-    async def login(self, args):
-        return await self._login_web(args)
-
-    async def _login_web(self, args):
-        import asyncio
-
-        try:
-            from app.external_comms.platforms.whatsapp_bridge.client import get_whatsapp_bridge
-        except ImportError:
-            return False, "WhatsApp bridge not available. Ensure Node.js >= 18 is installed."
-
-        bridge = get_whatsapp_bridge()
-
-        # Start bridge if not already running
-        if not bridge.is_running:
-            try:
-                await bridge.start()
-            except Exception as e:
-                return False, f"Failed to start WhatsApp bridge: {e}"
-
-        # Wait for either QR code or ready (already authenticated)
-        event_type, event_data = await bridge.wait_for_qr_or_ready(timeout=60.0)
-
-        if event_type == "ready":
-            # Already authenticated — save credential, keep bridge running
-            # (start_listening will reuse it if still running and ready)
-            from app.external_comms.platforms.whatsapp_web import WhatsAppWebCredential
-            owner_phone = bridge.owner_phone or ""
-            owner_name = bridge.owner_name or ""
-            save_credential("whatsapp_web.json", WhatsAppWebCredential(
-                session_id="bridge",
-                owner_phone=owner_phone,
-                owner_name=owner_name,
-            ))
-            display = owner_phone or owner_name or "connected"
-            return True, f"WhatsApp Web connected: +{display}"
-
-        if event_type == "qr":
-            # Show QR code to user — try terminal first, then image fallback
-            qr_string = (event_data or {}).get("qr_string", "")
-            if qr_string:
-                try:
-                    import qrcode, sys
-                    qr = qrcode.QRCode(border=1)
-                    qr.add_data(qr_string)
-                    qr.make(fit=True)
-                    matrix = qr.get_matrix()
-                    lines = []
-                    for row in matrix:
-                        lines.append("".join("##" if cell else "  " for cell in row))
-                    qr_text = "\n".join(lines)
-                    sys.stderr.write(f"\n{qr_text}\n\n")
-                    sys.stderr.write("Scan the QR code above with WhatsApp on your phone\n\n")
-                    sys.stderr.flush()
-                    logger.info("[WhatsApp] QR code printed to terminal")
-                except Exception as e:
-                    logger.debug(f"[WhatsApp] Could not print QR to terminal: {e}")
-
-            # Also try opening as image in browser
-            qr_data_url = (event_data or {}).get("qr_data_url")
-            if qr_data_url:
-                import tempfile, base64 as b64, os
-                qr_b64 = qr_data_url
-                if qr_b64.startswith("data:image"):
-                    qr_b64 = qr_b64.split(",", 1)[1]
-                qr_path = os.path.join(tempfile.gettempdir(), "whatsapp_qr_bridge.png")
-                with open(qr_path, "wb") as f:
-                    f.write(b64.b64decode(qr_b64))
-                webbrowser.open(f"file://{qr_path}")
-
-            # Wait for ready after QR scan (up to 120s)
-            ready = await bridge.wait_for_ready(timeout=120.0)
-            if not ready:
-                return False, "Timed out waiting for QR scan. Run /whatsapp login again."
-
-            # Save credential with owner info, keep bridge running
-            # (start_listening will reuse it if still running and ready)
-            from app.external_comms.platforms.whatsapp_web import WhatsAppWebCredential
-            owner_phone = bridge.owner_phone or ""
-            owner_name = bridge.owner_name or ""
-            save_credential("whatsapp_web.json", WhatsAppWebCredential(
-                session_id="bridge",
-                owner_phone=owner_phone,
-                owner_name=owner_name,
-            ))
-            display = owner_phone or owner_name or "connected"
-            return True, f"WhatsApp Web connected: +{display}"
-
-        # Timeout
-        return False, "Timed out waiting for WhatsApp bridge. Run /whatsapp login again."
-
-    async def logout(self, args):
-        if not has_credential("whatsapp_web.json"):
-            return False, "No WhatsApp credentials found."
-        remove_credential("whatsapp_web.json")
-        # Stop the bridge and listener
-        try:
-            from app.external_comms.platforms.whatsapp_bridge.client import get_whatsapp_bridge
-            bridge = get_whatsapp_bridge()
-            if bridge.is_running:
-                await bridge.stop()
-            from app.external_comms.manager import get_external_comms_manager
-            manager = get_external_comms_manager()
-            if manager and "whatsapp_web" in manager._active_clients:
-                client = manager._active_clients["whatsapp_web"]
-                if hasattr(client, 'stop_listening'):
-                    await client.stop_listening()
-                del manager._active_clients["whatsapp_web"]
-        except Exception:
-            pass
-        # Keep session directory — session persists for quick reconnect
-        # Only a full "logout" (not disconnect) should delete the session
-            pass
-        return True, "WhatsApp disconnected."
-
-    async def status(self):
-        if not has_credential("whatsapp_web.json"):
-            return True, "WhatsApp: Not connected"
-        from app.external_comms.platforms.whatsapp_web import WhatsAppWebCredential
-        cred = load_credential("whatsapp_web.json", WhatsAppWebCredential)
-        if not cred:
-            return True, "WhatsApp: Not connected"
-        phone = cred.owner_phone or "unknown"
-        name = cred.owner_name or ""
-        label = f"+{phone}" + (f" ({name})" if name else "")
-        return True, f"WhatsApp: Connected\n  - {label}"
-
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Outlook
-# ═══════════════════════════════════════════════════════════════════
-
-class OutlookHandler(IntegrationHandler):
-    SCOPES = "Mail.Read Mail.Send Mail.ReadWrite User.Read offline_access"
-
-    async def login(self, args):
-        from app.config import OUTLOOK_CLIENT_ID
-        if not OUTLOOK_CLIENT_ID:
-            return False, "Not configured. Set OUTLOOK_CLIENT_ID env var (or use embedded credentials)."
-
-        # Generate PKCE code_verifier and code_challenge (RFC 7636)
-        code_verifier = secrets.token_urlsafe(64)[:128]
-        code_challenge = base64.urlsafe_b64encode(
-            hashlib.sha256(code_verifier.encode()).digest()
-        ).decode().rstrip("=")
-
-        params = {
-            "client_id": OUTLOOK_CLIENT_ID,
-            "redirect_uri": REDIRECT_URI,
-            "response_type": "code",
-            "scope": self.SCOPES,
-            "response_mode": "query",
-            "state": secrets.token_urlsafe(32),
-            "code_challenge": code_challenge,
-            "code_challenge_method": "S256",
-        }
-        from agent_core import run_oauth_flow_async
-        code, error = await run_oauth_flow_async(
-            f"https://login.microsoftonline.com/common/oauth2/v2.0/authorize?{urlencode(params)}"
-        )
-        if error:
-            return False, f"Outlook OAuth failed: {error}"
-
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.post(
-                "https://login.microsoftonline.com/common/oauth2/v2.0/token",
-                data={
-                    "client_id": OUTLOOK_CLIENT_ID,
-                    "code": code,
-                    "redirect_uri": REDIRECT_URI,
-                    "grant_type": "authorization_code",
-                    "code_verifier": code_verifier,
-                    "scope": self.SCOPES,
-                },
-            ) as r:
-                if r.status != 200:
-                    return False, f"Token exchange failed: {await r.text()}"
-                tokens = await r.json()
-
-            async with s.get(
-                "https://graph.microsoft.com/v1.0/me",
-                headers={"Authorization": f"Bearer {tokens['access_token']}"},
-            ) as r:
-                if r.status != 200:
-                    return False, "Failed to fetch user info."
-                info = await r.json()
-
-        user_email = info.get("mail") or info.get("userPrincipalName", "")
-
-        from app.external_comms.platforms.outlook import OutlookCredential
-        save_credential("outlook.json", OutlookCredential(
-            access_token=tokens["access_token"],
-            refresh_token=tokens.get("refresh_token", ""),
-            token_expiry=time.time() + tokens.get("expires_in", 3600),
-            client_id=OUTLOOK_CLIENT_ID,
-            email=user_email,
-        ))
-        return True, f"Outlook connected as {user_email}"
-
-    async def logout(self, args):
-        if not has_credential("outlook.json"):
-            return False, "No Outlook credentials found."
-        remove_credential("outlook.json")
-        return True, "Removed Outlook credential."
-
-    async def status(self):
-        if not has_credential("outlook.json"):
-            return True, "Outlook: Not connected"
-        from app.external_comms.platforms.outlook import OutlookCredential
-        cred = load_credential("outlook.json", OutlookCredential)
-        email = cred.email if cred else "unknown"
-        return True, f"Outlook: Connected\n  - {email}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# WhatsApp Business
-# ═══════════════════════════════════════════════════════════════════
-
-class WhatsAppBusinessHandler(IntegrationHandler):
-    async def login(self, args):
-        if len(args) < 2: return False, "Usage: /whatsapp-business login <access_token> <phone_number_id>"
-        access_token, phone_number_id = args[0], args[1]
-
-        # Validate by calling the API
-        import aiohttp
-        async with aiohttp.ClientSession() as s:
-            async with s.get(
-                f"https://graph.facebook.com/v21.0/{phone_number_id}",
-                headers={"Authorization": f"Bearer {access_token}"},
-            ) as r:
-                if r.status != 200: return False, f"Invalid credentials: {r.status}"
-
-        from app.external_comms.platforms.whatsapp_business import WhatsAppBusinessCredential
-        save_credential("whatsapp_business.json", WhatsAppBusinessCredential(
-            access_token=access_token, phone_number_id=phone_number_id,
-        ))
-        return True, f"WhatsApp Business connected (phone number ID: {phone_number_id})"
-
-    async def logout(self, args):
-        if not has_credential("whatsapp_business.json"):
-            return False, "No WhatsApp Business credentials found."
-        remove_credential("whatsapp_business.json")
-        return True, "Removed WhatsApp Business credential."
-
-    async def status(self):
-        if not has_credential("whatsapp_business.json"):
-            return True, "WhatsApp Business: Not connected"
-        from app.external_comms.platforms.whatsapp_business import WhatsAppBusinessCredential
-        cred = load_credential("whatsapp_business.json", WhatsAppBusinessCredential)
-        pid = cred.phone_number_id if cred else "unknown"
-        return True, f"WhatsApp Business: Connected\n  - Phone Number ID: {pid}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Jira (API token)
-# ═══════════════════════════════════════════════════════════════════
-
-class JiraHandler(IntegrationHandler):
-    async def login(self, args):
-        if len(args) < 3:
-            return False, "Usage: /jira login <domain> <email> <api_token>\nGet an API token from https://id.atlassian.com/manage-profile/security/api-tokens"
-        domain, email, api_token = args[0], args[1], args[2]
-
-        # Normalize domain
-        clean_domain = domain.strip().rstrip("/")
-        if clean_domain.startswith("https://"):
-            clean_domain = clean_domain[len("https://"):]
-        if clean_domain.startswith("http://"):
-            clean_domain = clean_domain[len("http://"):]
-        # Auto-append .atlassian.net if user only entered the subdomain
-        if "." not in clean_domain:
-            clean_domain = f"{clean_domain}.atlassian.net"
-
-        email = email.strip()
-        api_token = api_token.strip()
-
-        # Validate by calling /myself (try API v3, then v2 as fallback)
-        import httpx as _httpx
-        raw_auth = base64.b64encode(f"{email}:{api_token}".encode()).decode()
-        auth_headers = {"Authorization": f"Basic {raw_auth}", "Accept": "application/json"}
-
-        data = None
-        last_status = 0
-        try:
-            for api_ver in ("3", "2"):
-                url = f"https://{clean_domain}/rest/api/{api_ver}/myself"
-                logger.info(f"[Jira] Trying {url} with email={email}")
-                r = _httpx.get(url, headers=auth_headers, timeout=15, follow_redirects=True)
-                if r.status_code == 200:
-                    data = r.json()
-                    break
-                body = r.text
-                logger.warning(f"[Jira] API v{api_ver} returned HTTP {r.status_code}: {body[:300]}")
-                last_status = r.status_code
-
-            if data is None:
-                hints = [f"Tried: https://{clean_domain}/rest/api/3/myself"]
-                if last_status == 401:
-                    hints.append("Ensure you are using an API token, not your account password.")
-                    hints.append("The email must match your Atlassian account email exactly.")
-                    hints.append("Generate a token at: https://id.atlassian.com/manage-profile/security/api-tokens")
-                elif last_status == 403:
-                    hints.append("Your account may not have REST API access. Check Jira permissions.")
-                elif last_status == 404:
-                    hints.append(f"Domain '{clean_domain}' not reachable or has no REST API.")
-                hint_str = "\n".join(f"  - {h}" for h in hints)
-                return False, f"Jira auth failed (HTTP {last_status}).\n{hint_str}"
-        except _httpx.ConnectError:
-            return False, f"Cannot connect to https://{clean_domain} — check the domain name."
-        except Exception as e:
-            return False, f"Jira connection error: {e}"
-
-        from app.external_comms.platforms.jira import JiraCredential
-        save_credential("jira.json", JiraCredential(
-            domain=clean_domain,
-            email=email,
-            api_token=api_token,
-        ))
-        display_name = data.get("displayName", email)
-        return True, f"Jira connected as {display_name} ({clean_domain})"
-
-    async def logout(self, args):
-        if not has_credential("jira.json"):
-            return False, "No Jira credentials found."
-        try:
-            from app.external_comms.manager import get_external_comms_manager
-            manager = get_external_comms_manager()
-            if manager:
-                await manager.stop_platform("jira")
-        except Exception:
-            pass
-        remove_credential("jira.json")
-        return True, "Removed Jira credential."
-
-    async def status(self):
-        if not has_credential("jira.json"):
-            return True, "Jira: Not connected"
-        from app.external_comms.platforms.jira import JiraCredential
-        cred = load_credential("jira.json", JiraCredential)
-        if not cred:
-            return True, "Jira: Not connected"
-        domain = cred.domain or cred.site_url or "unknown"
-        email = cred.email or "OAuth"
-        labels = cred.watch_labels
-        label_info = f" [watching: {', '.join(labels)}]" if labels else ""
-        return True, f"Jira: Connected\n  - {email} ({domain}){label_info}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# GitHub (personal access token)
-# ═══════════════════════════════════════════════════════════════════
-
-class GitHubHandler(IntegrationHandler):
-    async def login(self, args):
-        if not args:
-            return False, "Usage: /github login <personal_access_token>\nGenerate one at: https://github.com/settings/tokens"
-        token = args[0].strip()
-
-        import httpx as _httpx
-        try:
-            r = _httpx.get(
-                "https://api.github.com/user",
-                headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
-                timeout=15,
-            )
-            if r.status_code != 200:
-                return False, f"GitHub auth failed (HTTP {r.status_code}). Check your token."
-            data = r.json()
-        except Exception as e:
-            return False, f"GitHub connection error: {e}"
-
-        from app.external_comms.platforms.github import GitHubCredential
-        save_credential("github.json", GitHubCredential(
-            access_token=token,
-            username=data.get("login", ""),
-        ))
-        return True, f"GitHub connected as @{data.get('login')} ({data.get('name', '')})"
-
-    async def logout(self, args):
-        if not has_credential("github.json"):
-            return False, "No GitHub credentials found."
-        try:
-            from app.external_comms.manager import get_external_comms_manager
-            manager = get_external_comms_manager()
-            if manager:
-                await manager.stop_platform("github")
-        except Exception:
-            pass
-        remove_credential("github.json")
-        return True, "Removed GitHub credential."
-
-    async def status(self):
-        if not has_credential("github.json"):
-            return True, "GitHub: Not connected"
-        from app.external_comms.platforms.github import GitHubCredential
-        cred = load_credential("github.json", GitHubCredential)
-        if not cred:
-            return True, "GitHub: Not connected"
-        username = cred.username or "unknown"
-        tag = cred.watch_tag
-        tag_info = f" [tag: {tag}]" if tag else ""
-        repos_info = f" [repos: {', '.join(cred.watch_repos)}]" if cred.watch_repos else ""
-        return True, f"GitHub: Connected\n  - @{username}{tag_info}{repos_info}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Twitter/X (API key + secret + access tokens)
-# ═══════════════════════════════════════════════════════════════════
-
-class TwitterHandler(IntegrationHandler):
-    async def login(self, args):
-        if len(args) < 4:
-            return False, "Usage: /twitter login <api_key> <api_secret> <access_token> <access_token_secret>\nGet these from developer.x.com"
-        api_key, api_secret, access_token, access_token_secret = args[0].strip(), args[1].strip(), args[2].strip(), args[3].strip()
-
-        # Validate by calling /users/me
-        try:
-            from app.external_comms.platforms.twitter import TwitterCredential, _oauth1_header
-            import httpx as _httpx
-
-            url = "https://api.twitter.com/2/users/me"
-            params = {"user.fields": "id,name,username"}
-            auth_hdr = _oauth1_header("GET", url, params, api_key, api_secret, access_token, access_token_secret)
-            r = _httpx.get(url, headers={"Authorization": auth_hdr}, params=params, timeout=15)
-            if r.status_code != 200:
-                return False, f"Twitter auth failed (HTTP {r.status_code}). Check your API credentials.\nGet them from developer.x.com → Dashboard → Keys and tokens"
-            data = r.json().get("data", {})
-        except Exception as e:
-            return False, f"Twitter connection error: {e}"
-
-        save_credential("twitter.json", TwitterCredential(
-            api_key=api_key,
-            api_secret=api_secret,
-            access_token=access_token,
-            access_token_secret=access_token_secret,
-            user_id=data.get("id", ""),
-            username=data.get("username", ""),
-        ))
-        return True, f"Twitter/X connected as @{data.get('username')} ({data.get('name', '')})"
-
-    async def logout(self, args):
-        if not has_credential("twitter.json"):
-            return False, "No Twitter credentials found."
-        try:
-            from app.external_comms.manager import get_external_comms_manager
-            manager = get_external_comms_manager()
-            if manager:
-                await manager.stop_platform("twitter")
-        except Exception:
-            pass
-        remove_credential("twitter.json")
-        return True, "Removed Twitter credential."
-
-    async def status(self):
-        if not has_credential("twitter.json"):
-            return True, "Twitter/X: Not connected"
-        from app.external_comms.platforms.twitter import TwitterCredential
-        cred = load_credential("twitter.json", TwitterCredential)
-        if not cred:
-            return True, "Twitter/X: Not connected"
-        username = cred.username or "unknown"
-        tag_info = f" [tag: {cred.watch_tag}]" if cred.watch_tag else ""
-        return True, f"Twitter/X: Connected\n  - @{username}{tag_info}"
-
-
-# ═══════════════════════════════════════════════════════════════════
-# Registry
-# ═══════════════════════════════════════════════════════════════════
-
-INTEGRATION_HANDLERS: dict[str, IntegrationHandler] = {
-    "google":             GoogleHandler(),
-    "slack":              SlackHandler(),
-    "notion":             NotionHandler(),
-    "linkedin":           LinkedInHandler(),
-    "discord":            DiscordHandler(),
-    "telegram":           TelegramHandler(),
-    "whatsapp":           WhatsAppHandler(),
-    "outlook":            OutlookHandler(),
-    "whatsapp_business":  WhatsAppBusinessHandler(),
-    "jira":               JiraHandler(),
-    "github":             GitHubHandler(),
-    "twitter":            TwitterHandler(),
-}
diff --git a/app/data/action/generate_image.py b/app/data/action/generate_image.py
index f2aa6987..03bc887d 100644
--- a/app/data/action/generate_image.py
+++ b/app/data/action/generate_image.py
@@ -254,20 +254,12 @@ def _ensure_package(pkg_name):
 
     try:
         from google import genai
+        from google.genai import types
         from PIL import Image
         import io
         import base64
 
-        # Configure the API
-        genai.configure(api_key=api_key)
-
-        # Use Nano Banana Pro (Gemini 3 Pro Image) model
-        # Model name: gemini-3-pro-image-preview
-        model = genai.GenerativeModel("gemini-3-pro-image-preview")
-
-        # Build the generation request
-        # Nano Banana Pro uses a different API pattern - it's a multimodal model
-        # that generates images through the generate_content method
+        client = genai.Client(api_key=api_key)
 
         # Prepare reference images if provided
         image_parts = []
@@ -276,7 +268,6 @@ def _ensure_package(pkg_name):
                 try:
                     with open(ref_path, 'rb') as f:
                         image_data = f.read()
-                    # Determine mime type
                     ext = os.path.splitext(ref_path)[1].lower()
                     mime_map = {
                         '.png': 'image/png',
@@ -286,10 +277,9 @@ def _ensure_package(pkg_name):
                         '.webp': 'image/webp'
                     }
                     mime_type = mime_map.get(ext, 'image/png')
-                    image_parts.append({
-                        'mime_type': mime_type,
-                        'data': base64.b64encode(image_data).decode('utf-8')
-                    })
+                    image_parts.append(
+                        types.Part.from_bytes(data=image_data, mime_type=mime_type)
+                    )
                 except Exception:
                     pass  # Skip invalid reference images
 
@@ -306,22 +296,11 @@ def _ensure_package(pkg_name):
         if negative_prompt:
             generation_prompt += f"\n- Avoid: {negative_prompt}"
 
-        # Prepare content parts
-        content_parts = []
-        for img_part in image_parts:
-            content_parts.append({
-                'inline_data': img_part
-            })
+        content_parts = list(image_parts)
         content_parts.append(generation_prompt)
 
-        # Configure generation settings
-        generation_config = genai.types.GenerationConfig(
-            candidate_count=1,
-            # Enable image output
-        )
-
         # Safety settings
-        safety_settings = []
+        safety_settings = None
         if safety_filter_level != 'block_none':
             harm_block_threshold = {
                 'block_only_high': 'BLOCK_ONLY_HIGH',
@@ -329,18 +308,27 @@ def _ensure_package(pkg_name):
                 'block_low_and_above': 'BLOCK_LOW_AND_ABOVE'
             }.get(safety_filter_level, 'BLOCK_MEDIUM_AND_ABOVE')
 
-            for category in ['HARM_CATEGORY_HARASSMENT', 'HARM_CATEGORY_HATE_SPEECH',
-                           'HARM_CATEGORY_SEXUALLY_EXPLICIT', 'HARM_CATEGORY_DANGEROUS_CONTENT']:
-                safety_settings.append({
-                    'category': category,
-                    'threshold': harm_block_threshold
-                })
-
-        # Generate the image
-        response = model.generate_content(
-            content_parts,
-            generation_config=generation_config,
-            safety_settings=safety_settings if safety_settings else None
+            safety_settings = [
+                types.SafetySetting(category=category, threshold=harm_block_threshold)
+                for category in (
+                    'HARM_CATEGORY_HARASSMENT',
+                    'HARM_CATEGORY_HATE_SPEECH',
+                    'HARM_CATEGORY_SEXUALLY_EXPLICIT',
+                    'HARM_CATEGORY_DANGEROUS_CONTENT',
+                )
+            ]
+
+        generate_config = types.GenerateContentConfig(
+            candidate_count=1,
+            response_modalities=["TEXT", "IMAGE"],
+            image_config=types.ImageConfig(image_size=resolution),
+            safety_settings=safety_settings,
+        )
+
+        response = client.models.generate_content(
+            model="gemini-3-pro-image-preview",
+            contents=content_parts,
+            config=generate_config,
         )
 
         # Extract images from response
diff --git a/app/data/action/google_workspace/gmail_actions.py b/app/data/action/google_workspace/gmail_actions.py
deleted file mode 100644
index f5b28854..00000000
--- a/app/data/action/google_workspace/gmail_actions.py
+++ /dev/null
@@ -1,170 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="send_gmail",
-    description="Send an email via Gmail.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "to": {"type": "string", "description": "Recipient email address.", "example": "user@example.com"},
-        "subject": {"type": "string", "description": "Email subject.", "example": "Meeting Follow-up"},
-        "body": {"type": "string", "description": "Email body text.", "example": "Hi, here are the notes..."},
-        "attachments": {"type": "array", "description": "Optional list of file paths to attach.", "example": []},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def send_gmail(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.send_email(
-            to=input_data["to"],
-            subject=input_data["subject"],
-            body=input_data["body"],
-            attachments=input_data.get("attachments"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "message": "Email sent."}
-        return {"status": "error", "message": result.get("error", "Failed to send email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="list_gmail",
-    description="List recent emails from Gmail inbox.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "count": {"type": "integer", "description": "Number of recent emails to list.", "example": 5},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def list_gmail(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.list_emails(n=input_data.get("count", 5))
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to list emails.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_gmail",
-    description="Get details of a specific Gmail message by ID.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "message_id": {"type": "string", "description": "Gmail message ID.", "example": "18abc123def"},
-        "full_body": {"type": "boolean", "description": "Whether to include full email body.", "example": False},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_gmail(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.get_email(
-            message_id=input_data["message_id"],
-            full_body=input_data.get("full_body", False),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to get email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="read_top_emails",
-    description="Read the top N recent emails with details.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "count": {"type": "integer", "description": "Number of emails to read.", "example": 5},
-        "full_body": {"type": "boolean", "description": "Include full body text.", "example": False},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def read_top_emails(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.read_top_emails(
-            n=input_data.get("count", 5),
-            full_body=input_data.get("full_body", False),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to read emails.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_google_workspace_email",
-    description="Send email via Google Workspace.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "to_email": {"type": "string", "description": "Recipient.", "example": "user@example.com"},
-        "subject": {"type": "string", "description": "Subject.", "example": "Hello"},
-        "body": {"type": "string", "description": "Body.", "example": "Hi"},
-        "from_email": {"type": "string", "description": "Optional sender email.", "example": "me@example.com"},
-        "attachments": {"type": "array", "description": "Attachments.", "example": []},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def send_google_workspace_email(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.send_email(
-            to=input_data["to_email"],
-            subject=input_data["subject"],
-            body=input_data["body"],
-            from_email=input_data.get("from_email"),
-            attachments=input_data.get("attachments"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "message": "Email sent.", "result": result.get("result")}
-        return {"status": "error", "message": result.get("error", "Failed to send email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="read_recent_google_workspace_emails",
-    description="Read recent emails.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "n": {"type": "integer", "description": "Count.", "example": 5},
-        "full_body": {"type": "boolean", "description": "Full body.", "example": False},
-        "from_email": {"type": "string", "description": "Optional sender email.", "example": "me@example.com"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def read_recent_google_workspace_emails(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.read_top_emails(
-            n=input_data.get("n", 5),
-            full_body=input_data.get("full_body", False),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to read emails.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/google_workspace/google_calendar_actions.py b/app/data/action/google_workspace/google_calendar_actions.py
deleted file mode 100644
index 4eec5814..00000000
--- a/app/data/action/google_workspace/google_calendar_actions.py
+++ /dev/null
@@ -1,156 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="create_google_meet",
-    description="Create a Google Calendar event with a Google Meet link.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "event_data": {"type": "object", "description": "Calendar event data with summary, start, end, conferenceData.", "example": {}},
-        "calendar_id": {"type": "string", "description": "Calendar ID (default: primary).", "example": "primary"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def create_google_meet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.create_meet_event(
-            calendar_id=input_data.get("calendar_id", "primary"),
-            event_data=input_data.get("event_data"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to create event.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="check_calendar_availability",
-    description="Check Google Calendar free/busy availability.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "time_min": {"type": "string", "description": "Start time in ISO 8601 format.", "example": "2024-01-15T09:00:00Z"},
-        "time_max": {"type": "string", "description": "End time in ISO 8601 format.", "example": "2024-01-15T17:00:00Z"},
-        "calendar_id": {"type": "string", "description": "Calendar ID (default: primary).", "example": "primary"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def check_calendar_availability(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.check_availability(
-            calendar_id=input_data.get("calendar_id", "primary"),
-            time_min=input_data.get("time_min"),
-            time_max=input_data.get("time_max"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to check availability.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="check_availability_and_schedule",
-    description="Schedule meeting if free.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "start_time": {"type": "string", "description": "Start time.", "example": "2024-01-01T10:00:00"},
-        "end_time": {"type": "string", "description": "End time.", "example": "2024-01-01T11:00:00"},
-        "summary": {"type": "string", "description": "Summary.", "example": "Meeting"},
-        "description": {"type": "string", "description": "Description.", "example": "Details"},
-        "attendees": {"type": "array", "description": "Attendees.", "example": ["a@b.com"]},
-        "from_email": {"type": "string", "description": "Sender.", "example": "me@example.com"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def check_availability_and_schedule(input_data: dict) -> dict:
-    try:
-        import uuid
-        from datetime import datetime
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-
-        start_time = datetime.fromisoformat(input_data["start_time"])
-        end_time = datetime.fromisoformat(input_data["end_time"])
-
-        # Step 1: Check availability
-        avail = client.check_availability(
-            calendar_id="primary",
-            time_min=start_time.isoformat() + "Z",
-            time_max=end_time.isoformat() + "Z",
-        )
-
-        if "error" in avail:
-            return {
-                "status": "error",
-                "reason": "Google Calendar FreeBusy API error",
-                "details": avail,
-            }
-
-        busy_slots = (
-            avail.get("result", {})
-            .get("calendars", {})
-            .get("primary", {})
-            .get("busy", [])
-        )
-
-        if busy_slots:
-            return {
-                "status": "busy",
-                "reason": "Time slot is already occupied",
-                "conflicting_events": busy_slots,
-            }
-
-        # Step 2: Schedule the meeting
-        attendees = input_data.get("attendees") or []
-        formatted_attendees = [{"email": a} for a in attendees]
-
-        event_payload = {
-            "summary": input_data["summary"],
-            "description": input_data.get("description", ""),
-            "start": {
-                "dateTime": start_time.isoformat() + "Z",
-                "timeZone": "UTC",
-            },
-            "end": {
-                "dateTime": end_time.isoformat() + "Z",
-                "timeZone": "UTC",
-            },
-            "attendees": formatted_attendees,
-            "conferenceData": {
-                "createRequest": {
-                    "requestId": f"meet-{uuid.uuid4()}",
-                    "conferenceSolutionKey": {"type": "hangoutsMeet"},
-                }
-            },
-        }
-
-        result = client.create_meet_event(
-            calendar_id="primary",
-            event_data=event_payload,
-        )
-
-        if "error" in result:
-            return {
-                "status": "error",
-                "reason": "Google Calendar API error",
-                "details": result,
-            }
-
-        return {
-            "status": "success",
-            "reason": "Meeting scheduled successfully.",
-            "event": result.get("result", result),
-        }
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/google_workspace/google_drive_actions.py b/app/data/action/google_workspace/google_drive_actions.py
deleted file mode 100644
index 6c40a849..00000000
--- a/app/data/action/google_workspace/google_drive_actions.py
+++ /dev/null
@@ -1,156 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="list_drive_files",
-    description="List files in a Google Drive folder.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "folder_id": {"type": "string", "description": "Google Drive folder ID.", "example": "root"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def list_drive_files(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.list_drive_files(folder_id=input_data["folder_id"])
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to list files.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="create_drive_folder",
-    description="Create a new folder in Google Drive.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "name": {"type": "string", "description": "Folder name.", "example": "Project Files"},
-        "parent_folder_id": {"type": "string", "description": "Optional parent folder ID.", "example": ""},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def create_drive_folder(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.create_drive_folder(
-            name=input_data["name"],
-            parent_folder_id=input_data.get("parent_folder_id"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to create folder.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="move_drive_file",
-    description="Move a file to a different Google Drive folder.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "file_id": {"type": "string", "description": "File ID to move.", "example": "abc123"},
-        "destination_folder_id": {"type": "string", "description": "Destination folder ID.", "example": "def456"},
-        "source_folder_id": {"type": "string", "description": "Current parent folder ID.", "example": "root"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def move_drive_file(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.move_drive_file(
-            file_id=input_data["file_id"],
-            add_parents=input_data["destination_folder_id"],
-            remove_parents=input_data.get("source_folder_id", ""),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to move file.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="find_drive_folder_by_name",
-    description="Find folder by name.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "name": {"type": "string", "description": "Name.", "example": "Folder"},
-        "parent_folder_id": {"type": "string", "description": "Parent.", "example": "root"},
-        "from_email": {"type": "string", "description": "Email.", "example": "me@example.com"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def find_drive_folder_by_name(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        result = client.find_drive_folder_by_name(
-            name=input_data["name"],
-            parent_folder_id=input_data.get("parent_folder_id"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to find folder.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="resolve_drive_folder_path",
-    description="Resolve folder path.",
-    action_sets=["google_workspace"],
-    input_schema={
-        "path": {"type": "string", "description": "Path.", "example": "Root/Folder"},
-        "from_email": {"type": "string", "description": "Email.", "example": "me@example.com"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def resolve_drive_folder_path(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.google_workspace import GoogleWorkspaceClient
-        client = GoogleWorkspaceClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Google credential. Use /google login first."}
-        path = input_data["path"]
-
-        parts = [p for p in path.split("/") if p]
-        if parts and parts[0].lower() == "root":
-            parts = parts[1:]
-
-        current_folder_id = "root"
-
-        for part in parts:
-            result = client.find_drive_folder_by_name(
-                name=part,
-                parent_folder_id=current_folder_id,
-            )
-
-            if "error" in result:
-                return {"status": "error", "reason": result.get("error", "API error")}
-
-            folder = result.get("result")
-            if not folder:
-                return {
-                    "status": "not_found",
-                    "reason": f"Folder '{part}' not found",
-                    "folder_id": None,
-                }
-
-            current_folder_id = folder["id"]
-
-        return {"status": "success", "folder_id": current_folder_id}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/integrations/__init__.py b/app/data/action/integrations/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/app/data/action/integrations/_helpers.py b/app/data/action/integrations/_helpers.py
new file mode 100644
index 00000000..95e9317f
--- /dev/null
+++ b/app/data/action/integrations/_helpers.py
@@ -0,0 +1,224 @@
+"""Action-side helpers — collapse the repeated try/has_credentials/wrap pattern.
+
+Each action used to be ~14 lines of skeleton wrapped around a single
+client method call. With ``run_client`` an action becomes ~5 lines:
+
+    from app.data.action.integrations._helpers import run_client
+
+    @action(name="send_discord_message", ...)
+    async def send_discord_message(input_data: dict) -> dict:
+        return await run_client(
+            "discord", "bot_send_message",
+            channel_id=input_data["channel_id"],
+            content=input_data["content"],
+        )
+
+For sync actions, use ``run_client_sync`` (same API, no await).
+
+Some clients return ``{"ok": True, "result": ...}`` / ``{"error": ...}``
+envelopes (Outlook, Jira, etc.). Pass ``unwrap_envelope=True`` to
+extract the inner ``result`` on success or surface the inner ``error``
+message on failure. Pair with ``success_message="..."`` when the action
+should report a fixed success string instead of the inner result.
+
+Actions that do real pre/post-processing (parsing labels, recording to
+conversation history, building complex payloads) keep their explicit
+form — the helper is only for the boilerplate-heavy 80% case.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Dict, Optional
+
+
+def record_outgoing_message(platform_name: str, recipient: str, text: str) -> None:
+    """Best-effort: record an outgoing platform message into the agent's conversation history.
+
+    Used by integration actions that send messages on behalf of the agent
+    (Telegram, WhatsApp, etc.) so the conversation transcript reflects what
+    the agent emitted, not just what came back. Silently no-ops if the
+    state manager is not reachable — never raises.
+    """
+    try:
+        import app.internal_action_interface as iai
+        sm = iai.InternalActionInterface.state_manager
+        if sm:
+            label = f"[Sent via {platform_name} to {recipient}]: {text}"
+            sm.event_stream_manager.record_conversation_message(
+                f"agent message to platform: {platform_name}", label,
+            )
+            sm._append_to_conversation_history("agent", label)
+    except Exception:
+        pass
+
+
+def _resolve_handler(integration: str):
+    """Resolve a handler by handler-name first, then by client platform_id (e.g. 'google_workspace' -> google handler)."""
+    try:
+        from craftos_integrations import get_handler, get_registered_handler_names
+        handler = get_handler(integration)
+        if handler is not None:
+            return handler, integration
+        for name in get_registered_handler_names():
+            h = get_handler(name)
+            spec = getattr(h, "spec", None)
+            if spec and getattr(spec, "platform_id", None) == integration:
+                return h, name
+    except Exception:
+        pass
+    return None, integration
+
+
+def _no_cred_message(integration: str) -> str:
+    handler, slash_name = _resolve_handler(integration)
+    display = handler.display_name if handler and handler.display_name else integration
+    return f"No {display} credential. Use /{slash_name} login first."
+
+
+def _shape_result(
+    raw: Any,
+    *,
+    unwrap_envelope: bool,
+    success_message: Optional[str],
+    fail_message: str,
+) -> Dict[str, Any]:
+    """Translate a client return value into the action response envelope."""
+    if unwrap_envelope and isinstance(raw, dict):
+        # Success envelope: {"ok": True, "result": ...}
+        if raw.get("ok") is True:
+            if success_message:
+                return {"status": "success", "message": success_message}
+            return {"status": "success", "result": raw.get("result", raw)}
+        # Explicit failure envelope: {"ok": False, "error": ...}
+        if raw.get("ok") is False:
+            return {"status": "error", "message": raw.get("error", fail_message)}
+        # Implicit failure envelope from craftos_integrations.helpers.request:
+        # 4xx/5xx HTTP responses (and caught exceptions) return
+        # {"error": "API error: 403", "details": "..."} with NO "ok" key.
+        # Without this branch, the next clauses fall through and wrap the
+        # error as {"status": "success"}, hiding the failure from the agent.
+        if "error" in raw:
+            return {
+                "status": "error",
+                "message": raw.get("error", fail_message),
+                "details": raw.get("details"),
+            }
+    if success_message and isinstance(raw, dict) and raw.get("status") == "error":
+        return {"status": "error", "message": raw.get("message") or raw.get("error", fail_message)}
+    if success_message:
+        return {"status": "success", "message": success_message}
+    return {"status": "success", "result": raw}
+
+
+async def run_client(
+    integration: str,
+    method_name: str,
+    *,
+    unwrap_envelope: bool = False,
+    success_message: Optional[str] = None,
+    fail_message: str = "Operation failed",
+    **kwargs,
+) -> Dict[str, Any]:
+    """Resolve client by integration, check creds, call method, wrap result.
+
+    The named method may be sync or async; coroutines are awaited.
+    """
+    from craftos_integrations import get_client
+    client = get_client(integration)
+    if client is None:
+        return {"status": "error", "message": f"Unknown integration: {integration}"}
+    if not client.has_credentials():
+        return {"status": "error", "message": _no_cred_message(integration)}
+    try:
+        method = getattr(client, method_name, None)
+        if method is None:
+            return {"status": "error", "message": f"Method {method_name!r} not found on {integration} client"}
+        raw = method(**kwargs)
+        if asyncio.iscoroutine(raw):
+            raw = await raw
+        return _shape_result(
+            raw,
+            unwrap_envelope=unwrap_envelope,
+            success_message=success_message,
+            fail_message=fail_message,
+        )
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def run_client_sync(
+    integration: str,
+    method_name: str,
+    *,
+    unwrap_envelope: bool = False,
+    success_message: Optional[str] = None,
+    fail_message: str = "Operation failed",
+    **kwargs,
+) -> Dict[str, Any]:
+    """Sync flavor of ``run_client`` for sync actions calling sync methods."""
+    from craftos_integrations import get_client
+    client = get_client(integration)
+    if client is None:
+        return {"status": "error", "message": f"Unknown integration: {integration}"}
+    if not client.has_credentials():
+        return {"status": "error", "message": _no_cred_message(integration)}
+    try:
+        method = getattr(client, method_name, None)
+        if method is None:
+            return {"status": "error", "message": f"Method {method_name!r} not found on {integration} client"}
+        raw = method(**kwargs)
+        if asyncio.iscoroutine(raw):
+            return {"status": "error", "message": f"{method_name!r} is async — use run_client (await) instead"}
+        return _shape_result(
+            raw,
+            unwrap_envelope=unwrap_envelope,
+            success_message=success_message,
+            fail_message=fail_message,
+        )
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+
+def get_client_or_error(integration: str):
+    """Resolve a client + run the credential check.
+
+    Returns a tuple ``(client, error_dict)``:
+      - on success: ``(client, None)``
+      - on failure: ``(None, {"status": "error", "message": ...})``
+
+    Use this in actions that return bespoke result shapes / do multi-step
+    logic and can't use ``run_client`` or ``with_client``::
+
+        def my_action(input_data):
+            client, err = get_client_or_error("google_workspace")
+            if err:
+                return err
+            ...
+    """
+    from craftos_integrations import get_client
+    client = get_client(integration)
+    if client is None:
+        return None, {"status": "error", "message": f"Unknown integration: {integration}"}
+    if not client.has_credentials():
+        return None, {"status": "error", "message": _no_cred_message(integration)}
+    return client, None
+
+
+async def with_client(integration: str, fn: Callable, *args, **kwargs) -> Dict[str, Any]:
+    """Call ``fn(client, *args, **kwargs)`` after credential check.
+
+    Use when an action needs to do more than a single method call:
+    multiple calls in sequence, payload building, etc. ``fn`` may be
+    sync or async. Wraps the return as ``{"status": "success", "result": ...}``;
+    for bespoke result shapes use ``get_client_or_error`` instead.
+    """
+    client, err = get_client_or_error(integration)
+    if err:
+        return err
+    try:
+        result = fn(client, *args, **kwargs)
+        if asyncio.iscoroutine(result):
+            result = await result
+        return {"status": "success", "result": result}
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/integrations/_integration_essentials.py b/app/data/action/integrations/_integration_essentials.py
new file mode 100644
index 00000000..02a78f2a
--- /dev/null
+++ b/app/data/action/integrations/_integration_essentials.py
@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+"""Inject just-in-time integration guidance into the routing-time prompt.
+
+When a user message mentions an integration by name (e.g. "send a whatsapp
+message..."), this helper looks up the integration's ``INTEGRATION.md`` and
+extracts its ``## Essentials`` block. That block goes into the routing
+prompt so the routing-time LLM has the workflow rules in context BEFORE
+deciding what to do — instead of asking the user for info the integration
+could look up itself.
+
+The match is intentionally loose (case-insensitive substring against
+integration ids + display names + first tokens). False positives are
+cheap (~200 tokens of extra context); false negatives are the whole
+reason this exists.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional
+
+# Project root → ``craftos_integrations/integrations/<id>/INTEGRATION.md``.
+# This file is at app/data/action/integrations/_integration_essentials.py
+# → parents[4] is the project root.
+_INTEGRATIONS_ROOT = (
+    Path(__file__).resolve().parents[4] / "craftos_integrations" / "integrations"
+)
+
+# Built lazily on first call so we don't import the registry at module load.
+_KEYWORD_INDEX: Optional[Dict[str, str]] = None
+
+
+def _build_keyword_index() -> Dict[str, str]:
+    """Map keyword variants → integration id.
+
+    Scans ``craftos_integrations/integrations/`` and treats each
+    non-underscore-prefixed subdirectory OR ``<id>.py`` file as an
+    integration id. Doing the file-system scan (rather than calling
+    ``integration_registry()``) sidesteps a startup ordering issue
+    where the registry isn't populated by the time the router fires
+    its first call.
+
+    Shorter ids are processed first so a generic keyword like "lark"
+    binds to ``lark``, not ``lark_calendar`` (specific integrations
+    keep their own ids as keys — the generic key just doesn't get
+    overwritten).
+    """
+    if not _INTEGRATIONS_ROOT.is_dir():
+        return {}
+
+    integration_ids: List[str] = []
+    for child in _INTEGRATIONS_ROOT.iterdir():
+        name = child.name
+        if name.startswith(("_", ".")) or name == "__pycache__":
+            continue
+        if child.is_dir():
+            integration_ids.append(name)
+        elif child.suffix == ".py":
+            integration_ids.append(child.stem)
+
+    # Shorter ids first → generic keys (e.g. "lark") land on the simpler one.
+    integration_ids.sort(key=len)
+
+    index: Dict[str, str] = {}
+    for integration_id in integration_ids:
+        keys = {integration_id, integration_id.replace("_", " ")}
+        first_token = integration_id.split("_", 1)[0]
+        if first_token != integration_id:
+            keys.add(first_token)
+        for key in keys:
+            key = key.lower().strip()
+            if key:
+                index.setdefault(key, integration_id)
+    return index
+
+
+def _get_keyword_index() -> Dict[str, str]:
+    global _KEYWORD_INDEX
+    if _KEYWORD_INDEX is None:
+        try:
+            _KEYWORD_INDEX = _build_keyword_index()
+        except Exception:
+            _KEYWORD_INDEX = {}
+    return _KEYWORD_INDEX
+
+
+def _extract_essentials(integration_id: str) -> Optional[str]:
+    """Extract the ``## Essentials`` block from an integration's docs.
+
+    Looks in two places, in order:
+      1. ``<id>/INTEGRATION.md`` (directory-style; used by integrations
+         that are themselves a directory, e.g. whatsapp_web with its bridge).
+      2. ``<id>.md`` (sibling file; used by single-file integrations).
+    """
+    candidates = [
+        _INTEGRATIONS_ROOT / integration_id / "INTEGRATION.md",
+        _INTEGRATIONS_ROOT / f"{integration_id}.md",
+    ]
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        match = re.search(
+            r"^##\s+Essentials\s*\n(.*?)(?=^##\s|\Z)",
+            text,
+            re.MULTILINE | re.DOTALL,
+        )
+        if match:
+            return match.group(1).strip()
+    return None
+
+
+def get_essentials_for_message(message: str) -> str:
+    """Build the integration-essentials block for the routing prompt.
+
+    Returns ``""`` when no known integration is mentioned. Otherwise
+    returns a tagged block listing each matched integration's essentials,
+    deduplicated.
+    """
+    if not message:
+        return ""
+    keyword_index = _get_keyword_index()
+    if not keyword_index:
+        return ""
+    lower = message.lower()
+    # Longer keys first so e.g. "telegram_user" wins over a bare "telegram".
+    sorted_keys = sorted(keyword_index.keys(), key=len, reverse=True)
+    matched_ids: List[str] = []
+    seen: set = set()
+    for key in sorted_keys:
+        integration_id = keyword_index[key]
+        if integration_id in seen:
+            continue
+        if key in lower:
+            seen.add(integration_id)
+            matched_ids.append(integration_id)
+    if not matched_ids:
+        return ""
+    blocks: List[str] = []
+    for integration_id in matched_ids:
+        essentials = _extract_essentials(integration_id)
+        if essentials:
+            blocks.append(f"### {integration_id}\n{essentials}")
+    if not blocks:
+        return ""
+    return (
+        "<integration_essentials>\n"
+        "Workflow guidance for integrations mentioned in the user's message. "
+        "Use this BEFORE asking the user for information the integration "
+        "could look up itself.\n\n"
+        + "\n\n".join(blocks)
+        + "\n</integration_essentials>"
+    )
diff --git a/app/data/action/integrations/_routing.py b/app/data/action/integrations/_routing.py
new file mode 100644
index 00000000..1f1de463
--- /dev/null
+++ b/app/data/action/integrations/_routing.py
@@ -0,0 +1,45 @@
+"""Host-side routing: which integration actions to expose to the agent's
+conversation-mode loop, given which integrations currently have credentials.
+
+This is a host concern — the package (``craftos_integrations``) only tells us
+which platforms are connected. The choice of which @action-decorated function
+names to surface for each platform is curation that lives here, alongside the
+action files themselves.
+
+If you add a new integration with new conversation-mode actions, add the
+mapping below.
+"""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from craftos_integrations import list_connected
+
+
+# Per-platform list of action names to expose when the integration is connected.
+# Keys are platform_ids (the same string handlers expose as ``handler.spec.platform_id``).
+PLATFORM_CONVERSATION_ACTIONS: Dict[str, List[str]] = {
+    "discord":           ["send_discord_message", "send_discord_dm"],
+    "github":            ["add_github_comment", "create_github_issue"],
+    "jira":              ["add_jira_comment", "create_jira_issue"],
+    "lark":              ["send_lark_message"],
+    "line":              ["send_line_message"],
+    "slack":             ["send_slack_message"],
+    "telegram_bot":      ["send_telegram_bot_message"],
+    "telegram_user":     ["send_telegram_user_message"],
+    "twitter":           ["post_tweet", "reply_to_tweet"],
+    "whatsapp_business": ["send_whatsapp_web_text_message"],
+    "whatsapp_web":      ["send_whatsapp_web_text_message"],
+}
+
+
+def get_messaging_actions_for_connected() -> List[str]:
+    """Action names to expose given current credential state. Deduped, order-preserving."""
+    seen = set()
+    out: List[str] = []
+    for platform_id in list_connected():
+        for name in PLATFORM_CONVERSATION_ACTIONS.get(platform_id, []):
+            if name not in seen:
+                seen.add(name)
+                out.append(name)
+    return out
diff --git a/app/data/action/discord/discord_actions.py b/app/data/action/integrations/discord/discord_actions.py
similarity index 50%
rename from app/data/action/discord/discord_actions.py
rename to app/data/action/integrations/discord/discord_actions.py
index 497f05da..b69f73ef 100644
--- a/app/data/action/discord/discord_actions.py
+++ b/app/data/action/integrations/discord/discord_actions.py
@@ -2,10 +2,9 @@
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
-# Bot actions
+# Bot actions (sync REST methods)
 # ═══════════════════════════════════════════════════════════════════════════════
 
-
 @action(
     name="send_discord_message",
     description="Send a message to a Discord channel.",
@@ -17,18 +16,11 @@
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def send_discord_message(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.bot_send_message(
-            channel_id=input_data["channel_id"],
-            content=input_data["content"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "bot_send_message",
+        channel_id=input_data["channel_id"], content=input_data["content"],
+    )
 
 
 @action(
@@ -42,18 +34,11 @@ def send_discord_message(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_discord_messages(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.get_messages(
-            channel_id=input_data["channel_id"],
-            limit=input_data.get("limit", 50),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "get_messages",
+        channel_id=input_data["channel_id"], limit=input_data.get("limit", 50),
+    )
 
 
 @action(
@@ -66,17 +51,8 @@ def get_discord_messages(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def list_discord_guilds(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.get_bot_guilds(
-            limit=input_data.get("limit", 100),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("discord", "get_bot_guilds", limit=input_data.get("limit", 100))
 
 
 @action(
@@ -89,17 +65,8 @@ def list_discord_guilds(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_discord_channels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.get_guild_channels(
-            guild_id=input_data["guild_id"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("discord", "get_guild_channels", guild_id=input_data["guild_id"])
 
 
 @action(
@@ -113,18 +80,11 @@ def get_discord_channels(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def send_discord_dm(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.send_dm(
-            recipient_id=input_data["recipient_id"],
-            content=input_data["content"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "send_dm",
+        recipient_id=input_data["recipient_id"], content=input_data["content"],
+    )
 
 
 @action(
@@ -138,18 +98,11 @@ def send_discord_dm(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def list_discord_guild_members(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.list_guild_members(
-            guild_id=input_data["guild_id"],
-            limit=input_data.get("limit", 100),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "list_guild_members",
+        guild_id=input_data["guild_id"], limit=input_data.get("limit", 100),
+    )
 
 
 @action(
@@ -159,31 +112,24 @@ def list_discord_guild_members(input_data: dict) -> dict:
     input_schema={
         "channel_id": {"type": "string", "description": "Channel ID.", "example": "123"},
         "message_id": {"type": "string", "description": "Message ID.", "example": "456"},
-        "emoji": {"type": "string", "description": "Emoji.", "example": "\ud83d\udc4d"},
+        "emoji": {"type": "string", "description": "Emoji.", "example": "👍"},
     },
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def add_discord_reaction(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.add_reaction(
-            channel_id=input_data["channel_id"],
-            message_id=input_data["message_id"],
-            emoji=input_data["emoji"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "add_reaction",
+        channel_id=input_data["channel_id"],
+        message_id=input_data["message_id"],
+        emoji=input_data["emoji"],
+    )
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # User-account actions (self-bot / personal automation)
 # ═══════════════════════════════════════════════════════════════════════════════
 
-
 @action(
     name="send_discord_user_message",
     description="Send user message (self-bot).",
@@ -195,18 +141,11 @@ def add_discord_reaction(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def send_discord_user_message(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.user_send_message(
-            channel_id=input_data["channel_id"],
-            content=input_data["content"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "user_send_message",
+        channel_id=input_data["channel_id"], content=input_data["content"],
+    )
 
 
 @action(
@@ -217,15 +156,8 @@ def send_discord_user_message(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_discord_user_guilds(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.user_get_guilds()
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("discord", "user_get_guilds")
 
 
 @action(
@@ -236,15 +168,8 @@ def get_discord_user_guilds(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_discord_user_dm_channels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.user_get_dm_channels()
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("discord", "user_get_dm_channels")
 
 
 @action(
@@ -258,25 +183,17 @@ def get_discord_user_dm_channels(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def send_discord_user_dm(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.user_send_dm(
-            recipient_id=input_data["recipient_id"],
-            content=input_data["content"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "discord", "user_send_dm",
+        recipient_id=input_data["recipient_id"], content=input_data["content"],
+    )
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
-# Voice actions
+# Voice actions (async — lazy-loads discord.py voice helpers)
 # ═══════════════════════════════════════════════════════════════════════════════
 
-
 @action(
     name="join_discord_voice_channel",
     description="Join voice channel.",
@@ -288,18 +205,11 @@ def send_discord_user_dm(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def join_discord_voice_channel(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = await client.join_voice(
-            guild_id=input_data["guild_id"],
-            channel_id=input_data["channel_id"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "discord", "join_voice",
+        guild_id=input_data["guild_id"], channel_id=input_data["channel_id"],
+    )
 
 
 @action(
@@ -310,17 +220,8 @@ async def join_discord_voice_channel(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def leave_discord_voice_channel(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = await client.leave_voice(
-            guild_id=input_data["guild_id"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("discord", "leave_voice", guild_id=input_data["guild_id"])
 
 
 @action(
@@ -334,18 +235,11 @@ async def leave_discord_voice_channel(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def speak_discord_voice_tts(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = await client.speak_tts(
-            guild_id=input_data["guild_id"],
-            text=input_data["text"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "discord", "speak_tts",
+        guild_id=input_data["guild_id"], text=input_data["text"],
+    )
 
 
 @action(
@@ -356,14 +250,5 @@ async def speak_discord_voice_tts(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_discord_voice_status(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.discord import DiscordClient
-        client = DiscordClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Discord credential. Use /discord login first."}
-        result = client.get_voice_status(
-            guild_id=input_data["guild_id"],
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("discord", "get_voice_status", guild_id=input_data["guild_id"])
diff --git a/app/data/action/github/github_actions.py b/app/data/action/integrations/github/github_actions.py
similarity index 62%
rename from app/data/action/github/github_actions.py
rename to app/data/action/integrations/github/github_actions.py
index a5d58b59..313e9ffb 100644
--- a/app/data/action/github/github_actions.py
+++ b/app/data/action/integrations/github/github_actions.py
@@ -1,9 +1,5 @@
 from agent_core import action
 
-
-_NO_CRED_MSG = "No GitHub credential. Use /github login first."
-
-
 # ------------------------------------------------------------------
 # Issues
 # ------------------------------------------------------------------
@@ -20,19 +16,15 @@
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def list_github_issues(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.list_issues(
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.list_issues(
             input_data["repo"],
             state=input_data.get("state", "open"),
             per_page=input_data.get("per_page", 30),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+        ),
+    )
 
 
 @action(
@@ -46,15 +38,11 @@ async def list_github_issues(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_github_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_issue(input_data["repo"], input_data["number"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.get_issue(input_data["repo"], input_data["number"]),
+    )
 
 
 @action(
@@ -72,25 +60,20 @@ async def get_github_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def create_github_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        labels_str = input_data.get("labels", "")
-        labels = [l.strip() for l in labels_str.split(",") if l.strip()] if labels_str else None
-        assignees_str = input_data.get("assignees", "")
-        assignees = [a.strip() for a in assignees_str.split(",") if a.strip()] if assignees_str else None
-        result = await client.create_issue(
+    from app.data.action.integrations._helpers import with_client
+    from app.utils.text import csv_list
+    labels = csv_list(input_data.get("labels", ""), default=None)
+    assignees = csv_list(input_data.get("assignees", ""), default=None)
+    return await with_client(
+        "github",
+        lambda c: c.create_issue(
             input_data["repo"],
             input_data["title"],
             body=input_data.get("body", ""),
             labels=labels,
             assignees=assignees,
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+        ),
+    )
 
 
 @action(
@@ -105,15 +88,11 @@ async def create_github_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def close_github_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.close_issue(input_data["repo"], input_data["number"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.close_issue(input_data["repo"], input_data["number"]),
+    )
 
 
 # ------------------------------------------------------------------
@@ -133,15 +112,11 @@ async def close_github_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def add_github_comment(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.create_comment(input_data["repo"], input_data["number"], input_data["body"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.create_comment(input_data["repo"], input_data["number"], input_data["body"]),
+    )
 
 
 # ------------------------------------------------------------------
@@ -161,18 +136,15 @@ async def add_github_comment(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def add_github_labels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        labels = [l.strip() for l in input_data["labels"].split(",") if l.strip()]
-        if not labels:
-            return {"status": "error", "message": "No labels provided."}
-        result = await client.add_labels(input_data["repo"], input_data["number"], labels)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    from app.utils.text import csv_list
+    labels = csv_list(input_data["labels"])
+    if not labels:
+        return {"status": "error", "message": "No labels provided."}
+    return await with_client(
+        "github",
+        lambda c: c.add_labels(input_data["repo"], input_data["number"], labels),
+    )
 
 
 # ------------------------------------------------------------------
@@ -191,19 +163,15 @@ async def add_github_labels(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def list_github_prs(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.list_pull_requests(
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.list_pull_requests(
             input_data["repo"],
             state=input_data.get("state", "open"),
             per_page=input_data.get("per_page", 30),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+        ),
+    )
 
 
 # ------------------------------------------------------------------
@@ -220,15 +188,8 @@ async def list_github_prs(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def list_github_repos(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.list_repos(per_page=input_data.get("per_page", 30))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("github", "list_repos", per_page=input_data.get("per_page", 30))
 
 
 @action(
@@ -242,19 +203,15 @@ async def list_github_repos(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def search_github_issues(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.search_issues(input_data["query"], per_page=input_data.get("per_page", 20))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "github",
+        lambda c: c.search_issues(input_data["query"], per_page=input_data.get("per_page", 20)),
+    )
 
 
 # ------------------------------------------------------------------
-# Watch Settings
+# Watch Settings (custom: bespoke success messages, sync)
 # ------------------------------------------------------------------
 
 @action(
@@ -269,10 +226,10 @@ async def search_github_issues(input_data: dict) -> dict:
 )
 def set_github_watch_tag(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
+        from craftos_integrations import get_client
+        client = get_client("github")
+        if not client or not client.has_credentials():
+            return {"status": "error", "message": "No GitHub credential. Use /github login first."}
         tag = input_data.get("tag", "").strip()
         client.set_watch_tag(tag)
         if tag:
@@ -294,12 +251,12 @@ def set_github_watch_tag(input_data: dict) -> dict:
 )
 def set_github_watch_repos(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.github import GitHubClient
-        client = GitHubClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        repos_str = input_data.get("repos", "")
-        repos = [r.strip() for r in repos_str.split(",") if r.strip()] if repos_str else []
+        from craftos_integrations import get_client
+        from app.utils.text import csv_list
+        client = get_client("github")
+        if not client or not client.has_credentials():
+            return {"status": "error", "message": "No GitHub credential. Use /github login first."}
+        repos = csv_list(input_data.get("repos", ""))
         client.set_watch_repos(repos)
         if repos:
             return {"status": "success", "message": f"Watching repos: {', '.join(repos)}"}
diff --git a/app/data/action/integrations/google_workspace/gmail_actions.py b/app/data/action/integrations/google_workspace/gmail_actions.py
new file mode 100644
index 00000000..5f77e50b
--- /dev/null
+++ b/app/data/action/integrations/google_workspace/gmail_actions.py
@@ -0,0 +1,130 @@
+from agent_core import action
+
+
+@action(
+    name="send_gmail",
+    description="Send an email via Gmail.",
+    action_sets=["gmail"],
+    input_schema={
+        "to": {"type": "string", "description": "Recipient email address.", "example": "user@example.com"},
+        "subject": {"type": "string", "description": "Email subject.", "example": "Meeting Follow-up"},
+        "body": {"type": "string", "description": "Email body text.", "example": "Hi, here are the notes..."},
+        "attachments": {"type": "array", "description": "Optional list of file paths to attach.", "example": []},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def send_gmail(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "send_email",
+        unwrap_envelope=True, success_message="Email sent.", fail_message="Failed to send email.",
+        to=input_data["to"],
+        subject=input_data["subject"],
+        body=input_data["body"],
+        attachments=input_data.get("attachments"),
+    )
+
+
+@action(
+    name="list_gmail",
+    description="List recent emails from Gmail inbox.",
+    action_sets=["gmail"],
+    input_schema={
+        "count": {"type": "integer", "description": "Number of recent emails to list.", "example": 5},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_gmail(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "list_emails",
+        unwrap_envelope=True, fail_message="Failed to list emails.",
+        n=input_data.get("count", 5),
+    )
+
+
+@action(
+    name="get_gmail",
+    description="Get details of a specific Gmail message by ID.",
+    action_sets=["gmail"],
+    input_schema={
+        "message_id": {"type": "string", "description": "Gmail message ID.", "example": "18abc123def"},
+        "full_body": {"type": "boolean", "description": "Whether to include full email body.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_gmail(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "get_email",
+        unwrap_envelope=True, fail_message="Failed to get email.",
+        message_id=input_data["message_id"],
+        full_body=input_data.get("full_body", False),
+    )
+
+
+@action(
+    name="read_top_emails",
+    description="Read the top N recent emails with details.",
+    action_sets=["gmail"],
+    input_schema={
+        "count": {"type": "integer", "description": "Number of emails to read.", "example": 5},
+        "full_body": {"type": "boolean", "description": "Include full body text.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def read_top_emails(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "read_top_emails",
+        unwrap_envelope=True, fail_message="Failed to read emails.",
+        n=input_data.get("count", 5),
+        full_body=input_data.get("full_body", False),
+    )
+
+
+@action(
+    name="send_google_workspace_email",
+    description="Send email via Google Workspace.",
+    action_sets=["gmail"],
+    input_schema={
+        "to_email": {"type": "string", "description": "Recipient.", "example": "user@example.com"},
+        "subject": {"type": "string", "description": "Subject.", "example": "Hello"},
+        "body": {"type": "string", "description": "Body.", "example": "Hi"},
+        "from_email": {"type": "string", "description": "Optional sender email.", "example": "me@example.com"},
+        "attachments": {"type": "array", "description": "Attachments.", "example": []},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def send_google_workspace_email(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "send_email",
+        unwrap_envelope=True, success_message="Email sent.", fail_message="Failed to send email.",
+        to=input_data["to_email"],
+        subject=input_data["subject"],
+        body=input_data["body"],
+        from_email=input_data.get("from_email"),
+        attachments=input_data.get("attachments"),
+    )
+
+
+@action(
+    name="read_recent_google_workspace_emails",
+    description="Read recent emails.",
+    action_sets=["gmail"],
+    input_schema={
+        "n": {"type": "integer", "description": "Count.", "example": 5},
+        "full_body": {"type": "boolean", "description": "Full body.", "example": False},
+        "from_email": {"type": "string", "description": "Optional sender email.", "example": "me@example.com"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def read_recent_google_workspace_emails(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "gmail", "read_top_emails",
+        unwrap_envelope=True, fail_message="Failed to read emails.",
+        n=input_data.get("n", 5),
+        full_body=input_data.get("full_body", False),
+    )
diff --git a/app/data/action/integrations/google_workspace/google_calendar_actions.py b/app/data/action/integrations/google_workspace/google_calendar_actions.py
new file mode 100644
index 00000000..c5556589
--- /dev/null
+++ b/app/data/action/integrations/google_workspace/google_calendar_actions.py
@@ -0,0 +1,112 @@
+from agent_core import action
+
+
+@action(
+    name="create_google_meet",
+    description="Create a Google Calendar event with a Google Meet link.",
+    action_sets=["google_calendar"],
+    input_schema={
+        "event_data": {"type": "object", "description": "Calendar event data with summary, start, end, conferenceData.", "example": {}},
+        "calendar_id": {"type": "string", "description": "Calendar ID (default: primary).", "example": "primary"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def create_google_meet(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_calendar", "create_meet_event",
+        unwrap_envelope=True, fail_message="Failed to create event.",
+        calendar_id=input_data.get("calendar_id", "primary"),
+        event_data=input_data.get("event_data"),
+    )
+
+
+@action(
+    name="check_calendar_availability",
+    description="Check Google Calendar free/busy availability.",
+    action_sets=["google_calendar"],
+    input_schema={
+        "time_min": {"type": "string", "description": "Start time in ISO 8601 format.", "example": "2024-01-15T09:00:00Z"},
+        "time_max": {"type": "string", "description": "End time in ISO 8601 format.", "example": "2024-01-15T17:00:00Z"},
+        "calendar_id": {"type": "string", "description": "Calendar ID (default: primary).", "example": "primary"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def check_calendar_availability(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_calendar", "check_availability",
+        unwrap_envelope=True, fail_message="Failed to check availability.",
+        calendar_id=input_data.get("calendar_id", "primary"),
+        time_min=input_data.get("time_min"),
+        time_max=input_data.get("time_max"),
+    )
+
+
+@action(
+    name="check_availability_and_schedule",
+    description="Schedule meeting if free.",
+    action_sets=["google_calendar"],
+    input_schema={
+        "start_time": {"type": "string", "description": "Start time.", "example": "2024-01-01T10:00:00"},
+        "end_time": {"type": "string", "description": "End time.", "example": "2024-01-01T11:00:00"},
+        "summary": {"type": "string", "description": "Summary.", "example": "Meeting"},
+        "description": {"type": "string", "description": "Description.", "example": "Details"},
+        "attendees": {"type": "array", "description": "Attendees.", "example": ["a@b.com"]},
+        "from_email": {"type": "string", "description": "Sender.", "example": "me@example.com"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def check_availability_and_schedule(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    """Two client calls + branching ("busy" early-exit) + custom result shape."""
+    import uuid
+    from datetime import datetime
+
+    try:
+        start_time = datetime.fromisoformat(input_data["start_time"])
+        end_time = datetime.fromisoformat(input_data["end_time"])
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+
+    avail = run_client_sync(
+        "google_calendar", "check_availability",
+        unwrap_envelope=True, fail_message="Google Calendar FreeBusy API error",
+        calendar_id="primary",
+        time_min=start_time.isoformat() + "Z",
+        time_max=end_time.isoformat() + "Z",
+    )
+    if avail["status"] == "error":
+        return {"status": "error", "reason": "Google Calendar FreeBusy API error", "details": avail}
+
+    busy_slots = avail.get("result", {}).get("calendars", {}).get("primary", {}).get("busy", [])
+    if busy_slots:
+        return {"status": "busy", "reason": "Time slot is already occupied", "conflicting_events": busy_slots}
+
+    attendees = input_data.get("attendees") or []
+    event_payload = {
+        "summary": input_data["summary"],
+        "description": input_data.get("description", ""),
+        "start": {"dateTime": start_time.isoformat() + "Z", "timeZone": "UTC"},
+        "end": {"dateTime": end_time.isoformat() + "Z", "timeZone": "UTC"},
+        "attendees": [{"email": a} for a in attendees],
+        "conferenceData": {
+            "createRequest": {
+                "requestId": f"meet-{uuid.uuid4()}",
+                "conferenceSolutionKey": {"type": "hangoutsMeet"},
+            }
+        },
+    }
+    result = run_client_sync(
+        "google_calendar", "create_meet_event",
+        unwrap_envelope=True, fail_message="Google Calendar API error",
+        calendar_id="primary",
+        event_data=event_payload,
+    )
+    if result["status"] == "error":
+        return {"status": "error", "reason": "Google Calendar API error", "details": result}
+    return {
+        "status": "success",
+        "reason": "Meeting scheduled successfully.",
+        "event": result.get("result", result),
+    }
diff --git a/app/data/action/integrations/google_workspace/google_docs_actions.py b/app/data/action/integrations/google_workspace/google_docs_actions.py
new file mode 100644
index 00000000..caec5923
--- /dev/null
+++ b/app/data/action/integrations/google_workspace/google_docs_actions.py
@@ -0,0 +1,155 @@
+from agent_core import action
+
+
+@action(
+    name="create_google_doc",
+    description="Create a new blank Google Doc with the given title. Returns the document ID and editable URL.",
+    action_sets=["google_docs"],
+    input_schema={
+        "title": {"type": "string", "description": "Title for the new document.", "example": "Meeting Notes"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def create_google_doc(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "create_document",
+        unwrap_envelope=True, fail_message="Failed to create Google Doc.",
+        title=input_data["title"],
+    )
+
+
+@action(
+    name="get_google_doc",
+    description="Fetch the full structured content of a Google Doc.",
+    action_sets=["google_docs"],
+    input_schema={
+        "document_id": {"type": "string", "description": "The Google Doc's document ID.", "example": "1abcDEF..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_google_doc(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "get_document",
+        unwrap_envelope=True, fail_message="Failed to fetch document.",
+        document_id=input_data["document_id"],
+    )
+
+
+@action(
+    name="get_google_doc_text",
+    description="Get a Google Doc as plain text. Returns title and the doc body flattened to a string.",
+    action_sets=["google_docs"],
+    input_schema={
+        "document_id": {"type": "string", "description": "The Google Doc's document ID.", "example": "1abcDEF..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_google_doc_text(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "get_document_text",
+        unwrap_envelope=True, fail_message="Failed to read document.",
+        document_id=input_data["document_id"],
+    )
+
+
+@action(
+    name="append_to_google_doc",
+    description="Append text to the end of a Google Doc.",
+    action_sets=["google_docs"],
+    input_schema={
+        "document_id": {"type": "string", "description": "The Google Doc's document ID.", "example": "1abcDEF..."},
+        "text": {"type": "string", "description": "Text to append.", "example": "\\n\\nFollow-up: ..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def append_to_google_doc(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "append_text",
+        unwrap_envelope=True, success_message="Text appended.", fail_message="Failed to append text.",
+        document_id=input_data["document_id"],
+        text=input_data["text"],
+    )
+
+
+@action(
+    name="replace_google_doc_text",
+    description="Find-and-replace across the entire Google Doc body. Returns the number of occurrences changed.",
+    action_sets=["google_docs"],
+    input_schema={
+        "document_id": {"type": "string", "description": "The Google Doc's document ID.", "example": "1abcDEF..."},
+        "find": {"type": "string", "description": "Text to find.", "example": "TODO"},
+        "replace": {"type": "string", "description": "Replacement text.", "example": "DONE"},
+        "match_case": {"type": "boolean", "description": "Whether the search is case-sensitive.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def replace_google_doc_text(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "replace_text",
+        unwrap_envelope=True, fail_message="Failed to replace text.",
+        document_id=input_data["document_id"],
+        find=input_data["find"],
+        replace=input_data["replace"],
+        match_case=input_data.get("match_case", False),
+    )
+
+
+@action(
+    name="list_google_docs",
+    description="List Google Docs the user owns or has access to, most recent first.",
+    action_sets=["google_docs"],
+    input_schema={
+        "max_results": {"type": "integer", "description": "Max number of docs to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_google_docs(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "list_documents",
+        unwrap_envelope=True, fail_message="Failed to list docs.",
+        max_results=input_data.get("max_results", 50),
+    )
+
+
+@action(
+    name="search_google_docs",
+    description="Search for Google Docs by title fragment.",
+    action_sets=["google_docs"],
+    input_schema={
+        "query": {"type": "string", "description": "Title fragment to search for.", "example": "Meeting"},
+        "max_results": {"type": "integer", "description": "Max number of docs to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def search_google_docs(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "search_documents",
+        unwrap_envelope=True, fail_message="Failed to search docs.",
+        query=input_data["query"],
+        max_results=input_data.get("max_results", 50),
+    )
+
+
+@action(
+    name="delete_google_doc",
+    description="Move a Google Doc to the Drive trash.",
+    action_sets=["google_docs"],
+    input_schema={
+        "document_id": {"type": "string", "description": "The Google Doc's document ID.", "example": "1abcDEF..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def delete_google_doc(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_docs", "delete_document",
+        unwrap_envelope=True, success_message="Document deleted.", fail_message="Failed to delete document.",
+        document_id=input_data["document_id"],
+    )
diff --git a/app/data/action/integrations/google_workspace/google_drive_actions.py b/app/data/action/integrations/google_workspace/google_drive_actions.py
new file mode 100644
index 00000000..2359f5db
--- /dev/null
+++ b/app/data/action/integrations/google_workspace/google_drive_actions.py
@@ -0,0 +1,116 @@
+from agent_core import action
+
+
+@action(
+    name="list_drive_files",
+    description="List files in a Google Drive folder.",
+    action_sets=["google_drive"],
+    input_schema={
+        "folder_id": {"type": "string", "description": "Google Drive folder ID.", "example": "root"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_drive_files(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_drive", "list_drive_files",
+        unwrap_envelope=True, fail_message="Failed to list files.",
+        folder_id=input_data["folder_id"],
+    )
+
+
+@action(
+    name="create_drive_folder",
+    description="Create a new folder in Google Drive.",
+    action_sets=["google_drive"],
+    input_schema={
+        "name": {"type": "string", "description": "Folder name.", "example": "Project Files"},
+        "parent_folder_id": {"type": "string", "description": "Optional parent folder ID.", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def create_drive_folder(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_drive", "create_drive_folder",
+        unwrap_envelope=True, fail_message="Failed to create folder.",
+        name=input_data["name"],
+        parent_folder_id=input_data.get("parent_folder_id"),
+    )
+
+
+@action(
+    name="move_drive_file",
+    description="Move a file to a different Google Drive folder.",
+    action_sets=["google_drive"],
+    input_schema={
+        "file_id": {"type": "string", "description": "File ID to move.", "example": "abc123"},
+        "destination_folder_id": {"type": "string", "description": "Destination folder ID.", "example": "def456"},
+        "source_folder_id": {"type": "string", "description": "Current parent folder ID.", "example": "root"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def move_drive_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_drive", "move_drive_file",
+        unwrap_envelope=True, fail_message="Failed to move file.",
+        file_id=input_data["file_id"],
+        add_parents=input_data["destination_folder_id"],
+        remove_parents=input_data.get("source_folder_id", ""),
+    )
+
+
+@action(
+    name="find_drive_folder_by_name",
+    description="Find folder by name.",
+    action_sets=["google_drive"],
+    input_schema={
+        "name": {"type": "string", "description": "Name.", "example": "Folder"},
+        "parent_folder_id": {"type": "string", "description": "Parent.", "example": "root"},
+        "from_email": {"type": "string", "description": "Email.", "example": "me@example.com"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def find_drive_folder_by_name(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_drive", "find_drive_folder_by_name",
+        unwrap_envelope=True, fail_message="Failed to find folder.",
+        name=input_data["name"],
+        parent_folder_id=input_data.get("parent_folder_id"),
+    )
+
+
+@action(
+    name="resolve_drive_folder_path",
+    description="Resolve folder path.",
+    action_sets=["google_drive"],
+    input_schema={
+        "path": {"type": "string", "description": "Path.", "example": "Root/Folder"},
+        "from_email": {"type": "string", "description": "Email.", "example": "me@example.com"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def resolve_drive_folder_path(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    """Walks the path one segment at a time — custom 'not_found' shape."""
+    parts = [p for p in input_data["path"].split("/") if p]
+    if parts and parts[0].lower() == "root":
+        parts = parts[1:]
+    current_folder_id = "root"
+
+    for part in parts:
+        result = run_client_sync(
+            "google_drive", "find_drive_folder_by_name",
+            unwrap_envelope=True, fail_message=f"Failed to look up '{part}'",
+            name=part, parent_folder_id=current_folder_id,
+        )
+        if result["status"] == "error":
+            return {"status": "error", "reason": result.get("message", "API error")}
+        folder = result.get("result")
+        if not folder:
+            return {"status": "not_found", "reason": f"Folder '{part}' not found", "folder_id": None}
+        current_folder_id = folder["id"]
+
+    return {"status": "success", "folder_id": current_folder_id}
diff --git a/app/data/action/integrations/google_workspace/google_youtube_actions.py b/app/data/action/integrations/google_workspace/google_youtube_actions.py
new file mode 100644
index 00000000..f554bc21
--- /dev/null
+++ b/app/data/action/integrations/google_workspace/google_youtube_actions.py
@@ -0,0 +1,208 @@
+from agent_core import action
+
+
+@action(
+    name="get_my_youtube_channel",
+    description="Return the authenticated user's YouTube channel info (id, title, subscriber/view counts).",
+    action_sets=["google_youtube"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_my_youtube_channel(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "get_my_channel",
+        unwrap_envelope=True, fail_message="Failed to fetch channel.",
+    )
+
+
+@action(
+    name="search_youtube",
+    description="Search YouTube for videos, channels, or playlists.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "query": {"type": "string", "description": "Search terms.", "example": "claude code tutorial"},
+        "type": {"type": "string", "description": "What to search for: video, channel, or playlist.", "example": "video"},
+        "max_results": {"type": "integer", "description": "Max number of results.", "example": 25},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def search_youtube(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "search",
+        unwrap_envelope=True, fail_message="YouTube search failed.",
+        query=input_data["query"],
+        type_filter=input_data.get("type", "video"),
+        max_results=input_data.get("max_results", 25),
+    )
+
+
+@action(
+    name="get_youtube_video",
+    description="Get full metadata for a YouTube video (snippet, statistics, content details).",
+    action_sets=["google_youtube"],
+    input_schema={
+        "video_id": {"type": "string", "description": "The YouTube video ID.", "example": "dQw4w9WgXcQ"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_youtube_video(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "get_video",
+        unwrap_envelope=True, fail_message="Failed to fetch video.",
+        video_id=input_data["video_id"],
+    )
+
+
+@action(
+    name="list_my_youtube_subscriptions",
+    description="List the channels the authenticated user is subscribed to.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "max_results": {"type": "integer", "description": "Max number of subscriptions to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_my_youtube_subscriptions(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "list_my_subscriptions",
+        unwrap_envelope=True, fail_message="Failed to list subscriptions.",
+        max_results=input_data.get("max_results", 50),
+    )
+
+
+@action(
+    name="list_my_youtube_playlists",
+    description="List playlists owned by the authenticated user.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "max_results": {"type": "integer", "description": "Max number of playlists to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_my_youtube_playlists(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "list_my_playlists",
+        unwrap_envelope=True, fail_message="Failed to list playlists.",
+        max_results=input_data.get("max_results", 50),
+    )
+
+
+@action(
+    name="list_youtube_playlist_items",
+    description="List videos in a YouTube playlist.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "playlist_id": {"type": "string", "description": "The playlist ID.", "example": "PLrAXt..."},
+        "max_results": {"type": "integer", "description": "Max number of items to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_youtube_playlist_items(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "list_playlist_items",
+        unwrap_envelope=True, fail_message="Failed to list playlist items.",
+        playlist_id=input_data["playlist_id"],
+        max_results=input_data.get("max_results", 50),
+    )
+
+
+@action(
+    name="subscribe_to_youtube_channel",
+    description="Subscribe the authenticated user to a YouTube channel.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "channel_id": {"type": "string", "description": "The channel ID to subscribe to.", "example": "UC..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def subscribe_to_youtube_channel(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "subscribe",
+        unwrap_envelope=True, success_message="Subscribed.", fail_message="Failed to subscribe.",
+        channel_id=input_data["channel_id"],
+    )
+
+
+@action(
+    name="unsubscribe_from_youtube_channel",
+    description="Remove a YouTube subscription. Takes the subscription ID (from list_my_youtube_subscriptions), not the channel ID.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "subscription_id": {"type": "string", "description": "The subscription record ID.", "example": "abc123..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def unsubscribe_from_youtube_channel(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "unsubscribe",
+        unwrap_envelope=True, success_message="Unsubscribed.", fail_message="Failed to unsubscribe.",
+        subscription_id=input_data["subscription_id"],
+    )
+
+
+@action(
+    name="rate_youtube_video",
+    description="Like, dislike, or clear your rating on a YouTube video.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "video_id": {"type": "string", "description": "The YouTube video ID.", "example": "dQw4w9WgXcQ"},
+        "rating": {"type": "string", "description": "One of: like, dislike, none.", "example": "like"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def rate_youtube_video(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "rate_video",
+        unwrap_envelope=True, fail_message="Failed to rate video.",
+        video_id=input_data["video_id"],
+        rating=input_data["rating"],
+    )
+
+
+@action(
+    name="post_youtube_comment",
+    description="Post a top-level comment on a YouTube video.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "video_id": {"type": "string", "description": "The YouTube video ID.", "example": "dQw4w9WgXcQ"},
+        "text": {"type": "string", "description": "Comment text.", "example": "Great video!"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def post_youtube_comment(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "post_comment",
+        unwrap_envelope=True, success_message="Comment posted.", fail_message="Failed to post comment.",
+        video_id=input_data["video_id"],
+        text=input_data["text"],
+    )
+
+
+@action(
+    name="get_youtube_video_comments",
+    description="Get top-level comments on a YouTube video, most recent first.",
+    action_sets=["google_youtube"],
+    input_schema={
+        "video_id": {"type": "string", "description": "The YouTube video ID.", "example": "dQw4w9WgXcQ"},
+        "max_results": {"type": "integer", "description": "Max number of comments to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_youtube_video_comments(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "google_youtube", "get_video_comments",
+        unwrap_envelope=True, fail_message="Failed to fetch comments.",
+        video_id=input_data["video_id"],
+        max_results=input_data.get("max_results", 50),
+    )
diff --git a/app/data/action/integration_management.py b/app/data/action/integrations/integration_management.py
similarity index 95%
rename from app/data/action/integration_management.py
rename to app/data/action/integrations/integration_management.py
index 8b36df72..40867546 100644
--- a/app/data/action/integration_management.py
+++ b/app/data/action/integrations/integration_management.py
@@ -52,7 +52,7 @@ def list_available_integrations(input_data: dict) -> dict:
         return {"status": "success", "integrations": [], "message": "Simulated mode"}
 
     try:
-        from app.external_comms.integration_settings import list_integrations
+        from craftos_integrations import list_integrations_sync as list_integrations
 
         integrations = list_integrations()
         filter_connected = input_data.get("filter_connected", False)
@@ -169,14 +169,17 @@ def connect_integration(input_data: dict) -> dict:
         return {"status": "error", "message": "integration_id is required."}
 
     try:
-        from app.external_comms.integration_settings import (
-            INTEGRATION_REGISTRY,
+        from craftos_integrations import (
+            connect_token as connect_integration_token,
+            connect_oauth as connect_integration_oauth,
+            connect_interactive as connect_integration_interactive,
             get_integration_fields,
-            connect_integration_token,
-            connect_integration_oauth,
-            connect_integration_interactive,
-            start_whatsapp_qr_session,
+            integration_registry,
         )
+        from craftos_integrations.integrations.whatsapp_web import (
+            start_qr_session as start_whatsapp_qr_session,
+        )
+        INTEGRATION_REGISTRY = integration_registry()
 
         if integration_id not in INTEGRATION_REGISTRY:
             available = ", ".join(INTEGRATION_REGISTRY.keys())
@@ -413,7 +416,9 @@ def check_integration_status(input_data: dict) -> dict:
     try:
         # If a session_id is provided, check WhatsApp QR session status
         if session_id and integration_id == "whatsapp":
-            from app.external_comms.integration_settings import check_whatsapp_session_status
+            from craftos_integrations.integrations.whatsapp_web import (
+                check_qr_session_status as check_whatsapp_session_status,
+            )
 
             loop = asyncio.new_event_loop()
             try:
@@ -429,7 +434,7 @@ def check_integration_status(input_data: dict) -> dict:
             }
 
         # Otherwise check general integration status
-        from app.external_comms.integration_settings import get_integration_info
+        from craftos_integrations import get_integration_info_sync as get_integration_info
 
         info = get_integration_info(integration_id)
         if not info:
@@ -504,7 +509,7 @@ def disconnect_integration(input_data: dict) -> dict:
         return {"status": "error", "message": "integration_id is required."}
 
     try:
-        from app.external_comms.integration_settings import disconnect_integration as _disconnect
+        from craftos_integrations import disconnect as _disconnect
 
         loop = asyncio.new_event_loop()
         try:
diff --git a/app/data/action/jira/jira_actions.py b/app/data/action/integrations/jira/jira_actions.py
similarity index 59%
rename from app/data/action/jira/jira_actions.py
rename to app/data/action/integrations/jira/jira_actions.py
index 9654bcfd..d7d929ce 100644
--- a/app/data/action/jira/jira_actions.py
+++ b/app/data/action/integrations/jira/jira_actions.py
@@ -1,17 +1,10 @@
 from agent_core import action
+from app.utils import csv_list
 
 
 _NO_CRED_MSG = "No Jira credential. Use /jira login first."
 
 
-def _jira_client():
-    from app.external_comms.platforms.jira import JiraClient
-    client = JiraClient()
-    if not client.has_credentials():
-        return None
-    return client
-
-
 # ------------------------------------------------------------------
 # Issues
 # ------------------------------------------------------------------
@@ -28,21 +21,14 @@ def _jira_client():
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def search_jira_issues(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        fields_str = input_data.get("fields", "")
-        fields_list = [f.strip() for f in fields_str.split(",") if f.strip()] if fields_str else None
-        result = await client.search_issues(
-            jql=input_data["jql"],
-            max_results=input_data.get("max_results", 20),
-            fields_list=fields_list,
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    fields_list = csv_list(input_data.get("fields", ""), default=None)
+    return await run_client(
+        "jira", "search_issues",
+        jql=input_data["jql"],
+        max_results=input_data.get("max_results", 20),
+        fields_list=fields_list,
+    )
 
 
 @action(
@@ -56,17 +42,12 @@ async def search_jira_issues(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_jira_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        fields_str = input_data.get("fields", "")
-        fields_list = [f.strip() for f in fields_str.split(",") if f.strip()] if fields_str else None
-        result = await client.get_issue(input_data["issue_key"], fields_list=fields_list)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    fields_list = csv_list(input_data.get("fields", ""), default=None)
+    return await with_client(
+        "jira",
+        lambda c: c.get_issue(input_data["issue_key"], fields_list=fields_list),
+    )
 
 
 @action(
@@ -86,25 +67,18 @@ async def get_jira_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def create_jira_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        labels_str = input_data.get("labels", "")
-        labels = [l.strip() for l in labels_str.split(",") if l.strip()] if labels_str else None
-        result = await client.create_issue(
-            project_key=input_data["project_key"],
-            summary=input_data["summary"],
-            issue_type=input_data.get("issue_type", "Task"),
-            description=input_data.get("description") or None,
-            assignee_id=input_data.get("assignee_id") or None,
-            labels=labels,
-            priority=input_data.get("priority") or None,
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    labels = csv_list(input_data.get("labels", ""), default=None)
+    return await run_client(
+        "jira", "create_issue",
+        project_key=input_data["project_key"],
+        summary=input_data["summary"],
+        issue_type=input_data.get("issue_type", "Task"),
+        description=input_data.get("description") or None,
+        assignee_id=input_data.get("assignee_id") or None,
+        labels=labels,
+        priority=input_data.get("priority") or None,
+    )
 
 
 @action(
@@ -121,24 +95,20 @@ async def create_jira_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def update_jira_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        fields_update = {}
-        if input_data.get("summary"):
-            fields_update["summary"] = input_data["summary"]
-        if input_data.get("priority"):
-            fields_update["priority"] = {"name": input_data["priority"]}
-        if input_data.get("labels"):
-            fields_update["labels"] = [l.strip() for l in input_data["labels"].split(",") if l.strip()]
-        if not fields_update:
-            return {"status": "error", "message": "No fields to update."}
-        result = await client.update_issue(input_data["issue_key"], fields_update)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    fields_update = {}
+    if input_data.get("summary"):
+        fields_update["summary"] = input_data["summary"]
+    if input_data.get("priority"):
+        fields_update["priority"] = {"name": input_data["priority"]}
+    if input_data.get("labels"):
+        fields_update["labels"] = csv_list(input_data["labels"])
+    if not fields_update:
+        return {"status": "error", "message": "No fields to update."}
+    return await with_client(
+        "jira",
+        lambda c: c.update_issue(input_data["issue_key"], fields_update),
+    )
 
 
 # ------------------------------------------------------------------
@@ -157,15 +127,11 @@ async def update_jira_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def add_jira_comment(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.add_comment(input_data["issue_key"], input_data["body"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "jira",
+        lambda c: c.add_comment(input_data["issue_key"], input_data["body"]),
+    )
 
 
 @action(
@@ -179,18 +145,13 @@ async def add_jira_comment(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_jira_comments(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_issue_comments(
-            input_data["issue_key"],
-            max_results=input_data.get("max_results", 20),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "jira",
+        lambda c: c.get_issue_comments(
+            input_data["issue_key"], max_results=input_data.get("max_results", 20),
+        ),
+    )
 
 
 # ------------------------------------------------------------------
@@ -207,15 +168,8 @@ async def get_jira_comments(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_jira_transitions(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_transitions(input_data["issue_key"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("jira", "get_transitions", issue_key=input_data["issue_key"])
 
 
 @action(
@@ -231,19 +185,15 @@ async def get_jira_transitions(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def transition_jira_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.transition_issue(
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "jira",
+        lambda c: c.transition_issue(
             input_data["issue_key"],
             input_data["transition_id"],
             comment=input_data.get("comment") or None,
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+        ),
+    )
 
 
 # ------------------------------------------------------------------
@@ -262,18 +212,14 @@ async def transition_jira_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def assign_jira_issue(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.assign_issue(
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "jira",
+        lambda c: c.assign_issue(
             input_data["issue_key"],
             account_id=input_data.get("account_id") or None,
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+        ),
+    )
 
 
 # ------------------------------------------------------------------
@@ -292,18 +238,14 @@ async def assign_jira_issue(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def add_jira_labels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        labels = [l.strip() for l in input_data["labels"].split(",") if l.strip()]
-        if not labels:
-            return {"status": "error", "message": "No labels provided."}
-        result = await client.add_labels(input_data["issue_key"], labels)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    labels = csv_list(input_data["labels"])
+    if not labels:
+        return {"status": "error", "message": "No labels provided."}
+    return await with_client(
+        "jira",
+        lambda c: c.add_labels(input_data["issue_key"], labels),
+    )
 
 
 @action(
@@ -318,18 +260,14 @@ async def add_jira_labels(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def remove_jira_labels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        labels = [l.strip() for l in input_data["labels"].split(",") if l.strip()]
-        if not labels:
-            return {"status": "error", "message": "No labels provided."}
-        result = await client.remove_labels(input_data["issue_key"], labels)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    labels = csv_list(input_data["labels"])
+    if not labels:
+        return {"status": "error", "message": "No labels provided."}
+    return await with_client(
+        "jira",
+        lambda c: c.remove_labels(input_data["issue_key"], labels),
+    )
 
 
 # ------------------------------------------------------------------
@@ -346,15 +284,10 @@ async def remove_jira_labels(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def list_jira_projects(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_projects(max_results=input_data.get("max_results", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "jira", "get_projects", max_results=input_data.get("max_results", 50),
+    )
 
 
 @action(
@@ -368,22 +301,15 @@ async def list_jira_projects(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def search_jira_users(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.search_users(
-            input_data["query"],
-            max_results=input_data.get("max_results", 10),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "jira",
+        lambda c: c.search_users(input_data["query"], max_results=input_data.get("max_results", 10)),
+    )
 
 
 # ------------------------------------------------------------------
-# Watch Tag (comment mention filter)
+# Watch Tag (custom: bespoke success messages, sync)
 # ------------------------------------------------------------------
 
 @action(
@@ -398,9 +324,9 @@ async def search_jira_users(input_data: dict) -> dict:
 )
 def set_jira_watch_tag(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
+        from craftos_integrations import get_client
+        client = get_client("jira")
+        if not client or not client.has_credentials():
             return {"status": "error", "message": _NO_CRED_MSG}
         tag = input_data.get("tag", "").strip()
         client.set_watch_tag(tag)
@@ -420,9 +346,9 @@ def set_jira_watch_tag(input_data: dict) -> dict:
 )
 def get_jira_watch_tag(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
+        from craftos_integrations import get_client
+        client = get_client("jira")
+        if not client or not client.has_credentials():
             return {"status": "error", "message": _NO_CRED_MSG}
         tag = client.get_watch_tag()
         if tag:
@@ -432,10 +358,6 @@ def get_jira_watch_tag(input_data: dict) -> dict:
         return {"status": "error", "message": str(e)}
 
 
-# ------------------------------------------------------------------
-# Watch Labels (issue label filter)
-# ------------------------------------------------------------------
-
 @action(
     name="set_jira_watch_labels",
     description="Set which labels the Jira listener watches for. Only issues with these labels will trigger events. Pass empty to watch all issues.",
@@ -448,12 +370,11 @@ def get_jira_watch_tag(input_data: dict) -> dict:
 )
 def set_jira_watch_labels(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
+        from craftos_integrations import get_client
+        client = get_client("jira")
+        if not client or not client.has_credentials():
             return {"status": "error", "message": _NO_CRED_MSG}
-        labels_str = input_data.get("labels", "")
-        labels = [l.strip() for l in labels_str.split(",") if l.strip()] if labels_str else []
+        labels = csv_list(input_data.get("labels", ""))
         client.set_watch_labels(labels)
         if labels:
             return {"status": "success", "message": f"Now watching issues with labels: {', '.join(labels)}"}
@@ -471,9 +392,9 @@ def set_jira_watch_labels(input_data: dict) -> dict:
 )
 def get_jira_watch_labels(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.jira import JiraClient
-        client = JiraClient()
-        if not client.has_credentials():
+        from craftos_integrations import get_client
+        client = get_client("jira")
+        if not client or not client.has_credentials():
             return {"status": "error", "message": _NO_CRED_MSG}
         labels = client.get_watch_labels()
         if labels:
diff --git a/app/data/action/integrations/lark/__init__.py b/app/data/action/integrations/lark/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/app/data/action/integrations/lark/lark_actions.py b/app/data/action/integrations/lark/lark_actions.py
new file mode 100644
index 00000000..7ac24ba9
--- /dev/null
+++ b/app/data/action/integrations/lark/lark_actions.py
@@ -0,0 +1,83 @@
+from agent_core import action
+
+
+@action(
+    name="send_lark_message",
+    description="Send a text message via Lark to a user (by open_id), group chat (by chat_id), or company email. Use this when the agent needs to push a message via Lark.",
+    action_sets=["lark"],
+    input_schema={
+        "to": {"type": "string", "description": "Recipient identifier — Lark open_id (ou_...), user_id, group chat_id (oc_...), or company email.", "example": "ou_abcdef0123456789"},
+        "text": {"type": "string", "description": "Message text.", "example": "Hello from CraftBot!"},
+        "receive_id_type": {"type": "string", "description": "How to interpret 'to': 'open_id' (default), 'user_id', 'email', 'chat_id', or 'union_id'.", "example": "open_id"},
+    },
+    output_schema={
+        "status": {"type": "string", "example": "success"},
+        "result": {"type": "object"},
+    },
+)
+async def send_lark_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import record_outgoing_message, run_client
+    record_outgoing_message("Lark", input_data["to"], input_data["text"])
+    return await run_client(
+        "lark", "send_text",
+        receive_id=input_data["to"], text=input_data["text"],
+        receive_id_type=input_data.get("receive_id_type") or "open_id",
+    )
+
+
+@action(
+    name="reply_lark_message",
+    description="Reply to a Lark message in-thread, using the original message id (om_...).",
+    action_sets=["lark"],
+    input_schema={
+        "message_id": {"type": "string", "description": "The original Lark message id (starts with 'om_').", "example": "om_abcdef0123"},
+        "text": {"type": "string", "description": "Reply text.", "example": "Got it"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def reply_lark_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark", "reply_text",
+        message_id=input_data["message_id"], text=input_data["text"],
+    )
+
+
+@action(
+    name="get_lark_user_by_email",
+    description="Look up a Lark user's open_id from their company email. Useful for 'message alice@example.com' workflows where only the email is known.",
+    action_sets=["lark"],
+    input_schema={
+        "email": {"type": "string", "description": "Company email address.", "example": "alice@example.com"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_lark_user_by_email(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("lark", "get_user_by_email", email=input_data["email"])
+
+
+@action(
+    name="list_lark_chats",
+    description="List Lark group chats the bot is a member of.",
+    action_sets=["lark"],
+    input_schema={
+        "page_size": {"type": "integer", "description": "Max chats to return (capped at 100).", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def list_lark_chats(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("lark", "list_chats", page_size=input_data.get("page_size", 50))
+
+
+@action(
+    name="get_lark_bot_info",
+    description="Get the connected Lark bot's profile (app name, open_id).",
+    action_sets=["lark"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_lark_bot_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("lark", "get_bot_info")
diff --git a/app/data/action/integrations/lark_calendar/__init__.py b/app/data/action/integrations/lark_calendar/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/app/data/action/integrations/lark_calendar/lark_calendar_actions.py b/app/data/action/integrations/lark_calendar/lark_calendar_actions.py
new file mode 100644
index 00000000..d6abaa6a
--- /dev/null
+++ b/app/data/action/integrations/lark_calendar/lark_calendar_actions.py
@@ -0,0 +1,226 @@
+from agent_core import action
+
+
+@action(
+    name="list_lark_calendars",
+    description="List the bot's accessible Lark calendars (its own primary plus any shared with it).",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "page_size": {"type": "integer", "description": "Max calendars to return (capped at 1000).", "example": 20},
+        "page_token": {"type": "string", "description": "Pagination cursor from a previous response.", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def list_lark_calendars(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "list_calendars",
+        page_size=input_data.get("page_size", 20),
+        page_token=input_data.get("page_token", ""),
+    )
+
+
+@action(
+    name="get_lark_primary_calendar",
+    description="Get the bot's primary Lark calendar — useful for finding the calendar_id to pass to other Calendar actions.",
+    action_sets=["lark_calendar"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def get_lark_primary_calendar(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("lark_calendar", "get_primary_calendar")
+
+
+@action(
+    name="list_lark_calendar_events",
+    description="List events on a Lark calendar between two Unix timestamps (seconds).",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id. Use list_lark_calendars or get_lark_primary_calendar to find it.", "example": "primary"},
+        "start_time": {"type": "integer", "description": "Window start as Unix timestamp in seconds.", "example": 1730000000},
+        "end_time": {"type": "integer", "description": "Window end as Unix timestamp in seconds.", "example": 1730086400},
+        "page_size": {"type": "integer", "description": "Max events to return (capped at 1000).", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def list_lark_calendar_events(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "list_events",
+        calendar_id=input_data["calendar_id"],
+        start_time=input_data["start_time"],
+        end_time=input_data["end_time"],
+        page_size=input_data.get("page_size", 50),
+    )
+
+
+@action(
+    name="get_lark_calendar_event",
+    description="Fetch a single Lark calendar event by id.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id holding the event.", "example": "primary"},
+        "event_id": {"type": "string", "description": "Event id.", "example": "0123abcd-..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def get_lark_calendar_event(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "get_event",
+        calendar_id=input_data["calendar_id"],
+        event_id=input_data["event_id"],
+    )
+
+
+@action(
+    name="create_lark_calendar_event",
+    description="Create a new event on a Lark calendar. To invite attendees, call add_lark_event_attendees afterwards with the returned event_id.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id to create the event in.", "example": "primary"},
+        "summary": {"type": "string", "description": "Event title.", "example": "Q2 planning"},
+        "start_time": {"type": "integer", "description": "Start as Unix timestamp in seconds.", "example": 1730000000},
+        "end_time": {"type": "integer", "description": "End as Unix timestamp in seconds.", "example": 1730003600},
+        "description": {"type": "string", "description": "Event body / agenda.", "example": "Review last quarter and align on Q2 goals."},
+        "location": {"type": "string", "description": "Physical or virtual location label.", "example": "Conf Room A"},
+        "with_video_meeting": {"type": "boolean", "description": "If true, Lark auto-attaches a Lark Meeting URL.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def create_lark_calendar_event(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "create_event",
+        calendar_id=input_data["calendar_id"],
+        summary=input_data["summary"],
+        start_time=input_data["start_time"],
+        end_time=input_data["end_time"],
+        description=input_data.get("description", ""),
+        location=input_data.get("location", ""),
+        with_video_meeting=input_data.get("with_video_meeting", False),
+    )
+
+
+@action(
+    name="update_lark_calendar_event",
+    description="Patch fields on an existing Lark calendar event. Only fields you supply are changed.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id holding the event.", "example": "primary"},
+        "event_id": {"type": "string", "description": "Event id to update.", "example": "0123abcd-..."},
+        "summary": {"type": "string", "description": "New event title (omit to keep).", "example": "Q2 planning (rescheduled)"},
+        "description": {"type": "string", "description": "New description (omit to keep).", "example": ""},
+        "start_time": {"type": "integer", "description": "New start as Unix seconds (omit to keep).", "example": 1730086400},
+        "end_time": {"type": "integer", "description": "New end as Unix seconds (omit to keep).", "example": 1730090000},
+        "location": {"type": "string", "description": "New location (omit to keep).", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def update_lark_calendar_event(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "update_event",
+        calendar_id=input_data["calendar_id"],
+        event_id=input_data["event_id"],
+        summary=input_data.get("summary"),
+        description=input_data.get("description"),
+        start_time=input_data.get("start_time"),
+        end_time=input_data.get("end_time"),
+        location=input_data.get("location"),
+    )
+
+
+@action(
+    name="delete_lark_calendar_event",
+    description="Delete a Lark calendar event by id.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id holding the event.", "example": "primary"},
+        "event_id": {"type": "string", "description": "Event id to delete.", "example": "0123abcd-..."},
+        "need_notification": {"type": "boolean", "description": "Email attendees about the cancellation.", "example": True},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def delete_lark_calendar_event(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "delete_event",
+        calendar_id=input_data["calendar_id"],
+        event_id=input_data["event_id"],
+        need_notification=input_data.get("need_notification", True),
+    )
+
+
+@action(
+    name="search_lark_calendar_events",
+    description="Full-text search over event titles and descriptions in a Lark calendar.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id to search.", "example": "primary"},
+        "query": {"type": "string", "description": "Search query.", "example": "planning"},
+        "start_time": {"type": "integer", "description": "Optional window start as Unix seconds.", "example": 1730000000},
+        "end_time": {"type": "integer", "description": "Optional window end as Unix seconds.", "example": 1732000000},
+        "page_size": {"type": "integer", "description": "Max results (capped at 100).", "example": 20},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def search_lark_calendar_events(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "search_events",
+        calendar_id=input_data["calendar_id"],
+        query=input_data["query"],
+        start_time=input_data.get("start_time"),
+        end_time=input_data.get("end_time"),
+        page_size=input_data.get("page_size", 20),
+    )
+
+
+@action(
+    name="add_lark_event_attendees",
+    description="Invite attendees to a Lark calendar event. Pass user_ids (open_ids), emails (for external attendees), or chat_ids (invites everyone in a group).",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "calendar_id": {"type": "string", "description": "Calendar id holding the event.", "example": "primary"},
+        "event_id": {"type": "string", "description": "Event id.", "example": "0123abcd-..."},
+        "user_ids": {"type": "array", "description": "Lark open_ids (ou_...) to invite.", "example": ["ou_abc"]},
+        "emails": {"type": "array", "description": "Email addresses to invite as external attendees.", "example": ["alice@example.com"]},
+        "chat_ids": {"type": "array", "description": "Lark group chat_ids (oc_...) — every member gets invited.", "example": []},
+        "need_notification": {"type": "boolean", "description": "Email/notify the attendees about the invite.", "example": True},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def add_lark_event_attendees(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "add_event_attendees",
+        calendar_id=input_data["calendar_id"],
+        event_id=input_data["event_id"],
+        user_ids=input_data.get("user_ids"),
+        emails=input_data.get("emails"),
+        chat_ids=input_data.get("chat_ids"),
+        need_notification=input_data.get("need_notification", True),
+    )
+
+
+@action(
+    name="check_lark_free_busy",
+    description="Bulk free/busy query — returns each user's busy intervals over a time window. Useful for finding a meeting slot that works for everyone.",
+    action_sets=["lark_calendar"],
+    input_schema={
+        "user_ids": {"type": "array", "description": "List of Lark open_ids (ou_...) to query.", "example": ["ou_abc", "ou_def"]},
+        "start_time": {"type": "integer", "description": "Window start as Unix timestamp in seconds.", "example": 1730000000},
+        "end_time": {"type": "integer", "description": "Window end as Unix timestamp in seconds.", "example": 1730086400},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def check_lark_free_busy(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_calendar", "check_free_busy",
+        user_ids=input_data["user_ids"],
+        start_time=input_data["start_time"],
+        end_time=input_data["end_time"],
+    )
diff --git a/app/data/action/integrations/lark_drive/__init__.py b/app/data/action/integrations/lark_drive/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/app/data/action/integrations/lark_drive/lark_drive_actions.py b/app/data/action/integrations/lark_drive/lark_drive_actions.py
new file mode 100644
index 00000000..160ae406
--- /dev/null
+++ b/app/data/action/integrations/lark_drive/lark_drive_actions.py
@@ -0,0 +1,138 @@
+from agent_core import action
+
+
+@action(
+    name="list_lark_drive_files",
+    description="List files and folders in Lark Drive. Pass an empty folder_token to list the root.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "folder_token": {"type": "string", "description": "Folder token to list inside. Empty string lists the root.", "example": ""},
+        "page_size": {"type": "integer", "description": "Max items to return (capped at 200).", "example": 50},
+        "page_token": {"type": "string", "description": "Pagination cursor from a previous response's next_page_token.", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def list_lark_drive_files(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "list_files",
+        folder_token=input_data.get("folder_token", ""),
+        page_size=input_data.get("page_size", 50),
+        page_token=input_data.get("page_token", ""),
+    )
+
+
+@action(
+    name="get_lark_drive_file_metadata",
+    description="Fetch metadata for one or more Lark Drive file tokens.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "file_tokens": {"type": "array", "description": "List of file tokens to look up.", "example": ["boxcnabcdef0123"]},
+        "doc_type": {"type": "string", "description": "Document type — 'file' (default), 'doc', 'docx', 'sheet', 'bitable', 'mindnote', 'slides'.", "example": "file"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def get_lark_drive_file_metadata(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "get_file_metadata",
+        file_tokens=input_data["file_tokens"],
+        doc_type=input_data.get("doc_type", "file"),
+    )
+
+
+@action(
+    name="create_lark_drive_folder",
+    description="Create a new folder in Lark Drive. Empty parent_folder_token creates at the root.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "name": {"type": "string", "description": "Folder name.", "example": "Reports 2026"},
+        "parent_folder_token": {"type": "string", "description": "Parent folder token. Empty string for root.", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def create_lark_drive_folder(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "create_folder",
+        name=input_data["name"],
+        parent_folder_token=input_data.get("parent_folder_token", ""),
+    )
+
+
+@action(
+    name="upload_lark_drive_file",
+    description="Upload a local file to a Lark Drive folder. Max 20MB — larger files require chunked upload (not yet supported).",
+    action_sets=["lark_drive"],
+    input_schema={
+        "file_path": {"type": "string", "description": "Absolute path to the local file to upload.", "example": "/home/user/report.pdf"},
+        "parent_folder_token": {"type": "string", "description": "Destination folder token in Lark Drive.", "example": "fldcnabcdef0123"},
+        "file_name": {"type": "string", "description": "Name to give the file in Drive. Defaults to basename of file_path.", "example": "report.pdf"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def upload_lark_drive_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "upload_file",
+        file_path=input_data["file_path"],
+        parent_folder_token=input_data["parent_folder_token"],
+        file_name=input_data.get("file_name", ""),
+    )
+
+
+@action(
+    name="download_lark_drive_file",
+    description="Download a file from Lark Drive to a local path.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "file_token": {"type": "string", "description": "Lark Drive file token.", "example": "boxcnabcdef0123"},
+        "dest_path": {"type": "string", "description": "Absolute local path to write the file to.", "example": "/home/user/Downloads/report.pdf"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def download_lark_drive_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "download_file",
+        file_token=input_data["file_token"],
+        dest_path=input_data["dest_path"],
+    )
+
+
+@action(
+    name="delete_lark_drive_file",
+    description="Delete a file or folder from Lark Drive by token.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "file_token": {"type": "string", "description": "Lark Drive file token to delete.", "example": "boxcnabcdef0123"},
+        "file_type": {"type": "string", "description": "Type — 'file' (default), 'folder', 'doc', 'docx', 'sheet', 'bitable', 'mindnote', 'shortcut', 'slides'.", "example": "file"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def delete_lark_drive_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "delete_file",
+        file_token=input_data["file_token"],
+        file_type=input_data.get("file_type", "file"),
+    )
+
+
+@action(
+    name="search_lark_drive_files",
+    description="Full-text search across files in Lark Drive that the bot has access to.",
+    action_sets=["lark_drive"],
+    input_schema={
+        "search_key": {"type": "string", "description": "Search query string.", "example": "Q1 report"},
+        "count": {"type": "integer", "description": "Max results to return (capped at 50).", "example": 20},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "result": {"type": "object"}},
+)
+async def search_lark_drive_files(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "lark_drive", "search_files",
+        search_key=input_data["search_key"],
+        count=input_data.get("count", 20),
+    )
diff --git a/app/data/action/integrations/line/__init__.py b/app/data/action/integrations/line/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/app/data/action/integrations/line/line_actions.py b/app/data/action/integrations/line/line_actions.py
new file mode 100644
index 00000000..e57da612
--- /dev/null
+++ b/app/data/action/integrations/line/line_actions.py
@@ -0,0 +1,111 @@
+from agent_core import action
+
+
+@action(
+    name="send_line_message",
+    description="Send a text message via LINE to a user, group, or room ID. Use this ONLY when the agent needs to push a message via LINE.",
+    action_sets=["line"],
+    input_schema={
+        "to": {"type": "string", "description": "LINE user ID, group ID, or room ID. Starts with U, C, or R.", "example": "U4af4980629..."},
+        "text": {"type": "string", "description": "Message text to send.", "example": "Hello from CraftBot!"},
+    },
+    output_schema={
+        "status": {"type": "string", "example": "success"},
+        "result": {"type": "object"},
+    },
+)
+async def send_line_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import record_outgoing_message, run_client
+    record_outgoing_message("LINE", input_data["to"], input_data["text"])
+    return await run_client(
+        "line", "push_text",
+        to=input_data["to"], text=input_data["text"],
+    )
+
+
+@action(
+    name="reply_line_message",
+    description="Reply to a LINE webhook event using its reply token (valid for ~1 minute after the event arrives). Free of quota; prefer over push when a reply token is available.",
+    action_sets=["line"],
+    input_schema={
+        "reply_token": {"type": "string", "description": "Reply token from the inbound LINE webhook event.", "example": "nHuyWi..."},
+        "text": {"type": "string", "description": "Reply text.", "example": "Got it!"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def reply_line_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "line", "reply_text",
+        reply_token=input_data["reply_token"], text=input_data["text"],
+    )
+
+
+@action(
+    name="multicast_line_message",
+    description="Send the same LINE text message to up to 500 user IDs in a single call. Counts against the monthly push quota for each recipient.",
+    action_sets=["line"],
+    input_schema={
+        "to": {"type": "array", "description": "List of LINE user IDs (max 500).", "example": ["U4af4980629...", "Ub1234..."]},
+        "text": {"type": "string", "description": "Message text.", "example": "Heads up team"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def multicast_line_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "line", "multicast_text",
+        to=input_data["to"], text=input_data["text"],
+    )
+
+
+@action(
+    name="broadcast_line_message",
+    description="Broadcast a LINE text message to every user that has the bot as a friend. Counts heavily against the monthly push quota — use sparingly.",
+    action_sets=["line"],
+    input_schema={
+        "text": {"type": "string", "description": "Message text.", "example": "Service announcement"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def broadcast_line_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("line", "broadcast_text", text=input_data["text"])
+
+
+@action(
+    name="get_line_profile",
+    description="Fetch a LINE user's display name and picture URL by user ID.",
+    action_sets=["line"],
+    input_schema={
+        "user_id": {"type": "string", "description": "LINE user ID (starts with U).", "example": "U4af4980629..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_line_profile(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("line", "get_profile", user_id=input_data["user_id"])
+
+
+@action(
+    name="get_line_bot_info",
+    description="Get the connected LINE bot's own profile (userId, displayName, picture).",
+    action_sets=["line"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_line_bot_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("line", "get_bot_info")
+
+
+@action(
+    name="get_line_quota",
+    description="Get the LINE bot's remaining monthly push-message quota.",
+    action_sets=["line"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_line_quota(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("line", "get_quota")
diff --git a/app/data/action/integrations/linkedin/linkedin_actions.py b/app/data/action/integrations/linkedin/linkedin_actions.py
new file mode 100644
index 00000000..d1a45f28
--- /dev/null
+++ b/app/data/action/integrations/linkedin/linkedin_actions.py
@@ -0,0 +1,492 @@
+from agent_core import action
+
+
+def _person_urn(client) -> str:
+    """LinkedIn URN of the authenticated user — used as author for posts/likes/comments."""
+    cred = client._load()
+    return f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
+
+
+# ------------------------------------------------------------------
+# Profile
+# ------------------------------------------------------------------
+
+@action(
+    name="get_linkedin_profile",
+    description="Get the authenticated user's LinkedIn profile.",
+    action_sets=["linkedin"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_profile(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_user_profile")
+
+
+# ------------------------------------------------------------------
+# Posts (text post / reshare / delete / get / list / org posts)
+# ------------------------------------------------------------------
+
+@action(
+    name="create_linkedin_post",
+    description="Create a text post on LinkedIn.",
+    action_sets=["linkedin"],
+    input_schema={
+        "text": {"type": "string", "description": "Post text (max 3000 chars).", "example": "Excited to share..."},
+        "visibility": {"type": "string", "description": "Visibility: PUBLIC, CONNECTIONS, or LOGGED_IN.", "example": "PUBLIC"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def create_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.create_text_post(
+            _person_urn(c),
+            input_data["text"],
+            visibility=input_data.get("visibility", "PUBLIC"),
+        ),
+    )
+
+
+@action(
+    name="delete_linkedin_post",
+    description="Delete a LinkedIn post.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def delete_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "delete_post", post_urn=input_data["post_urn"])
+
+
+@action(
+    name="get_linkedin_post",
+    description="Get a post.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_post", post_urn=input_data["post_urn"])
+
+
+@action(
+    name="get_my_linkedin_posts",
+    description="Get my posts.",
+    action_sets=["linkedin"],
+    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_my_linkedin_posts(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.get_posts_by_author(_person_urn(c), count=input_data.get("count", 50)),
+    )
+
+
+@action(
+    name="get_linkedin_organization_posts",
+    description="Get organization posts.",
+    action_sets=["linkedin"],
+    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_organization_posts(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "linkedin", "get_posts_by_author", author_urn=input_data["organization_urn"],
+    )
+
+
+@action(
+    name="reshare_linkedin_post",
+    description="Reshare a post.",
+    action_sets=["linkedin"],
+    input_schema={
+        "original_post_urn": {"type": "string", "description": "Original Post URN.", "example": "urn:li:share:123"},
+        "commentary": {"type": "string", "description": "Commentary.", "example": "Interesting!"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def reshare_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.reshare_post(
+            _person_urn(c),
+            input_data["original_post_urn"],
+            commentary=input_data.get("commentary", ""),
+        ),
+    )
+
+
+# ------------------------------------------------------------------
+# Reactions / Comments
+# ------------------------------------------------------------------
+
+@action(
+    name="like_linkedin_post",
+    description="Like a post.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def like_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.like_post(_person_urn(c), input_data["post_urn"]),
+    )
+
+
+@action(
+    name="unlike_linkedin_post",
+    description="Unlike a post.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def unlike_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.unlike_post(_person_urn(c), input_data["post_urn"]),
+    )
+
+
+@action(
+    name="get_linkedin_post_likes",
+    description="Get post likes.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_post_likes(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_post_reactions", post_urn=input_data["post_urn"])
+
+
+@action(
+    name="comment_on_linkedin_post",
+    description="Comment on a post.",
+    action_sets=["linkedin"],
+    input_schema={
+        "post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"},
+        "text": {"type": "string", "description": "Comment text.", "example": "Great post!"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def comment_on_linkedin_post(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.comment_on_post(_person_urn(c), input_data["post_urn"], input_data["text"]),
+    )
+
+
+@action(
+    name="get_linkedin_post_comments",
+    description="Get post comments.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_post_comments(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_post_comments", post_urn=input_data["post_urn"])
+
+
+@action(
+    name="delete_linkedin_comment",
+    description="Delete a comment.",
+    action_sets=["linkedin"],
+    input_schema={
+        "post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"},
+        "comment_urn": {"type": "string", "description": "Comment URN.", "example": "urn:li:comment:123"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def delete_linkedin_comment(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.delete_comment(_person_urn(c), input_data["post_urn"], input_data["comment_urn"]),
+    )
+
+
+# ------------------------------------------------------------------
+# Connections / Invitations / Messages
+# ------------------------------------------------------------------
+
+@action(
+    name="get_linkedin_connections",
+    description="Get the authenticated user's LinkedIn connections.",
+    action_sets=["linkedin"],
+    input_schema={
+        "count": {"type": "integer", "description": "Number of connections to return.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_connections(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_connections", count=input_data.get("count", 50))
+
+
+@action(
+    name="send_linkedin_message",
+    description="Send a message to LinkedIn users.",
+    action_sets=["linkedin"],
+    input_schema={
+        "recipient_urns": {"type": "array", "description": "List of recipient URNs (urn:li:person:xxx).", "example": []},
+        "subject": {"type": "string", "description": "Message subject.", "example": "Hello"},
+        "body": {"type": "string", "description": "Message body.", "example": "Hi, I wanted to connect..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_linkedin_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.send_message_to_recipients(
+            _person_urn(c),
+            input_data["recipient_urns"],
+            input_data["subject"],
+            input_data["body"],
+        ),
+    )
+
+
+@action(
+    name="send_linkedin_connection_request",
+    description="Send connection request.",
+    action_sets=["linkedin"],
+    input_schema={
+        "invitee_profile_urn": {"type": "string", "description": "Profile URN.", "example": "urn:li:person:123"},
+        "message": {"type": "string", "description": "Message.", "example": "Hi"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def send_linkedin_connection_request(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "linkedin", "send_connection_request",
+        invitee_profile_urn=input_data["invitee_profile_urn"],
+        message=input_data.get("message"),
+    )
+
+
+@action(
+    name="get_linkedin_sent_invitations",
+    description="Get sent invitations.",
+    action_sets=["linkedin"],
+    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_sent_invitations(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_sent_invitations", count=input_data.get("count", 50))
+
+
+@action(
+    name="get_linkedin_received_invitations",
+    description="Get received invitations.",
+    action_sets=["linkedin"],
+    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_received_invitations(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_received_invitations", count=input_data.get("count", 50))
+
+
+@action(
+    name="respond_to_linkedin_invitation",
+    description="Respond to invitation.",
+    action_sets=["linkedin"],
+    input_schema={
+        "invitation_urn": {"type": "string", "description": "Invitation URN.", "example": "urn:li:invitation:123"},
+        "action": {"type": "string", "description": "accept/ignore.", "example": "accept"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def respond_to_linkedin_invitation(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "linkedin", "respond_to_invitation",
+        invitation_urn=input_data["invitation_urn"],
+        action=input_data["action"],
+    )
+
+
+@action(
+    name="get_linkedin_conversations",
+    description="Get conversations.",
+    action_sets=["linkedin"],
+    input_schema={"count": {"type": "integer", "description": "Count.", "example": 20}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_conversations(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_conversations", count=input_data.get("count", 20))
+
+
+# ------------------------------------------------------------------
+# Search / Lookups
+# ------------------------------------------------------------------
+
+@action(
+    name="search_linkedin_jobs",
+    description="Search for job postings on LinkedIn.",
+    action_sets=["linkedin"],
+    input_schema={
+        "keywords": {"type": "string", "description": "Job search keywords.", "example": "software engineer"},
+        "location": {"type": "string", "description": "Optional location filter.", "example": ""},
+        "count": {"type": "integer", "description": "Number of results.", "example": 25},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def search_linkedin_jobs(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "linkedin", "search_jobs",
+        keywords=input_data["keywords"],
+        location=input_data.get("location"),
+        count=input_data.get("count", 25),
+    )
+
+
+@action(
+    name="get_linkedin_job_details",
+    description="Get job details.",
+    action_sets=["linkedin"],
+    input_schema={"job_id": {"type": "string", "description": "Job ID.", "example": "123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_job_details(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_job_details", job_id=input_data["job_id"])
+
+
+@action(
+    name="search_linkedin_companies",
+    description="Search companies.",
+    action_sets=["linkedin"],
+    input_schema={"keywords": {"type": "string", "description": "Keywords.", "example": "tech"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def search_linkedin_companies(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "search_companies", keywords=input_data["keywords"])
+
+
+@action(
+    name="lookup_linkedin_company",
+    description="Lookup company by vanity name.",
+    action_sets=["linkedin"],
+    input_schema={"vanity_name": {"type": "string", "description": "Vanity name.", "example": "microsoft"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def lookup_linkedin_company(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_company_by_vanity_name", vanity_name=input_data["vanity_name"])
+
+
+@action(
+    name="get_linkedin_person",
+    description="Get person profile by ID.",
+    action_sets=["linkedin"],
+    input_schema={"person_id": {"type": "string", "description": "Person ID.", "example": "123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_person(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_person", person_id=input_data["person_id"])
+
+
+# ------------------------------------------------------------------
+# Organizations / Analytics / Follow
+# ------------------------------------------------------------------
+
+@action(
+    name="get_linkedin_organizations",
+    description="Get user's organizations.",
+    action_sets=["linkedin"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_organizations(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_my_organizations")
+
+
+@action(
+    name="get_linkedin_organization_info",
+    description="Get organization info.",
+    action_sets=["linkedin"],
+    input_schema={"organization_id": {"type": "string", "description": "Org ID.", "example": "123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_organization_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_organization", organization_id=input_data["organization_id"])
+
+
+@action(
+    name="get_linkedin_organization_analytics",
+    description="Get organization analytics.",
+    action_sets=["linkedin"],
+    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_organization_analytics(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "linkedin", "get_organization_analytics",
+        organization_urn=input_data["organization_urn"],
+    )
+
+
+@action(
+    name="get_linkedin_post_analytics",
+    description="Get post analytics.",
+    action_sets=["linkedin"],
+    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_linkedin_post_analytics(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("linkedin", "get_post_analytics", share_urns=[input_data["post_urn"]])
+
+
+@action(
+    name="follow_linkedin_organization",
+    description="Follow organization.",
+    action_sets=["linkedin"],
+    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def follow_linkedin_organization(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.follow_organization(_person_urn(c), input_data["organization_urn"]),
+    )
+
+
+@action(
+    name="unfollow_linkedin_organization",
+    description="Unfollow organization.",
+    action_sets=["linkedin"],
+    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def unfollow_linkedin_organization(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "linkedin",
+        lambda c: c.unfollow_organization(_person_urn(c), input_data["organization_urn"]),
+    )
diff --git a/app/data/action/notion/notion_actions.py b/app/data/action/integrations/notion/notion_actions.py
similarity index 50%
rename from app/data/action/notion/notion_actions.py
rename to app/data/action/integrations/notion/notion_actions.py
index cacfc415..d014942e 100644
--- a/app/data/action/notion/notion_actions.py
+++ b/app/data/action/integrations/notion/notion_actions.py
@@ -12,15 +12,11 @@
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def search_notion(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.search(input_data["query"], filter_type=input_data.get("filter_type"))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "notion", "search",
+        query=input_data["query"], filter_type=input_data.get("filter_type"),
+    )
 
 
 @action(
@@ -33,15 +29,8 @@ def search_notion(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def get_notion_page(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.get_page(input_data["page_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("notion", "get_page", page_id=input_data["page_id"])
 
 
 @action(
@@ -57,18 +46,14 @@ def get_notion_page(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def create_notion_page(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.create_page(
-            input_data["parent_id"], input_data["parent_type"],
-            input_data["properties"], children=input_data.get("children"),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "notion", "create_page",
+        parent_id=input_data["parent_id"],
+        parent_type=input_data["parent_type"],
+        properties=input_data["properties"],
+        children=input_data.get("children"),
+    )
 
 
 @action(
@@ -83,19 +68,13 @@ def create_notion_page(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def query_notion_database(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.query_database(
-            input_data["database_id"],
-            filter_obj=input_data.get("filter"),
-            sorts=input_data.get("sorts"),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "notion", "query_database",
+        database_id=input_data["database_id"],
+        filter_obj=input_data.get("filter"),
+        sorts=input_data.get("sorts"),
+    )
 
 
 @action(
@@ -109,15 +88,11 @@ def query_notion_database(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def update_notion_page(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.update_page(input_data["page_id"], input_data["properties"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "notion", "update_page",
+        page_id=input_data["page_id"], properties=input_data["properties"],
+    )
 
 
 @action(
@@ -130,15 +105,8 @@ def update_notion_page(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}, "database": {"type": "object"}},
 )
 def get_notion_database_schema(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.get_database(input_data["database_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("notion", "get_database", database_id=input_data["database_id"])
 
 
 @action(
@@ -151,15 +119,8 @@ def get_notion_database_schema(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}, "content": {"type": "array"}},
 )
 def get_notion_page_content(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.get_block_children(input_data["page_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("notion", "get_block_children", block_id=input_data["page_id"])
 
 
 @action(
@@ -173,12 +134,8 @@ def get_notion_page_content(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 def append_notion_page_content(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.notion import NotionClient
-        client = NotionClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Notion credential. Use /notion login first."}
-        result = client.append_block_children(input_data["page_id"], input_data["children"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "notion", "append_block_children",
+        block_id=input_data["page_id"], children=input_data["children"],
+    )
diff --git a/app/data/action/integrations/outlook/outlook_actions.py b/app/data/action/integrations/outlook/outlook_actions.py
new file mode 100644
index 00000000..6294c72b
--- /dev/null
+++ b/app/data/action/integrations/outlook/outlook_actions.py
@@ -0,0 +1,116 @@
+from agent_core import action
+
+
+@action(
+    name="send_outlook_email",
+    description="Send an email via Outlook (Microsoft 365).",
+    action_sets=["outlook"],
+    input_schema={
+        "to": {"type": "string", "description": "Recipient email address.", "example": "user@example.com"},
+        "subject": {"type": "string", "description": "Email subject.", "example": "Meeting Follow-up"},
+        "body": {"type": "string", "description": "Email body text.", "example": "Hi, here are the notes..."},
+        "cc": {"type": "string", "description": "Optional CC recipients (comma-separated).", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def send_outlook_email(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "send_email",
+        unwrap_envelope=True, success_message="Email sent.", fail_message="Failed to send email.",
+        to=input_data["to"],
+        subject=input_data["subject"],
+        body=input_data["body"],
+        cc=input_data.get("cc"),
+    )
+
+
+@action(
+    name="list_outlook_emails",
+    description="List recent emails from Outlook inbox.",
+    action_sets=["outlook"],
+    input_schema={
+        "count": {"type": "integer", "description": "Number of recent emails to list.", "example": 10},
+        "unread_only": {"type": "boolean", "description": "Only show unread emails.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_outlook_emails(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "list_emails",
+        unwrap_envelope=True, fail_message="Failed to list emails.",
+        n=input_data.get("count", 10),
+        unread_only=input_data.get("unread_only", False),
+    )
+
+
+@action(
+    name="get_outlook_email",
+    description="Get full details of a specific Outlook email by message ID.",
+    action_sets=["outlook"],
+    input_schema={
+        "message_id": {"type": "string", "description": "Outlook message ID.", "example": "AAMk..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_outlook_email(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "get_email",
+        unwrap_envelope=True, fail_message="Failed to get email.",
+        message_id=input_data["message_id"],
+    )
+
+
+@action(
+    name="read_top_outlook_emails",
+    description="Read the top N recent Outlook emails with details.",
+    action_sets=["outlook"],
+    input_schema={
+        "count": {"type": "integer", "description": "Number of emails to read.", "example": 5},
+        "full_body": {"type": "boolean", "description": "Include full body text.", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def read_top_outlook_emails(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "read_top_emails",
+        unwrap_envelope=True, fail_message="Failed to read emails.",
+        n=input_data.get("count", 5),
+        full_body=input_data.get("full_body", False),
+    )
+
+
+@action(
+    name="mark_outlook_email_read",
+    description="Mark an Outlook email as read.",
+    action_sets=["outlook"],
+    input_schema={
+        "message_id": {"type": "string", "description": "Outlook message ID.", "example": "AAMk..."},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def mark_outlook_email_read(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "mark_as_read",
+        unwrap_envelope=True, success_message="Email marked as read.", fail_message="Failed to mark email.",
+        message_id=input_data["message_id"],
+    )
+
+
+@action(
+    name="list_outlook_folders",
+    description="List mail folders in Outlook.",
+    action_sets=["outlook"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def list_outlook_folders(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "outlook", "list_folders",
+        unwrap_envelope=True, fail_message="Failed to list folders.",
+    )
diff --git a/app/data/action/integrations/slack/slack_actions.py b/app/data/action/integrations/slack/slack_actions.py
new file mode 100644
index 00000000..7a95cc05
--- /dev/null
+++ b/app/data/action/integrations/slack/slack_actions.py
@@ -0,0 +1,190 @@
+from agent_core import action
+
+
+@action(
+    name="send_slack_message",
+    description="Send a message to a Slack channel or DM.",
+    action_sets=["slack"],
+    input_schema={
+        "channel": {"type": "string", "description": "Channel ID or name.", "example": "C01234567"},
+        "text": {"type": "string", "description": "Message text.", "example": "Hello team!"},
+        "thread_ts": {"type": "string", "description": "Optional thread timestamp for replies.", "example": ""},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_slack_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "slack", "send_message",
+        recipient=input_data["channel"],
+        text=input_data["text"],
+        thread_ts=input_data.get("thread_ts"),
+    )
+
+
+@action(
+    name="list_slack_channels",
+    description="List channels in the Slack workspace.",
+    action_sets=["slack"],
+    input_schema={
+        "limit": {"type": "integer", "description": "Max channels to return.", "example": 100},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "channels": {"type": "array"}},
+)
+def list_slack_channels(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("slack", "list_channels", limit=input_data.get("limit", 100))
+
+
+@action(
+    name="get_slack_channel_history",
+    description="Get message history from a Slack channel.",
+    action_sets=["slack"],
+    input_schema={
+        "channel": {"type": "string", "description": "Channel ID.", "example": "C01234567"},
+        "limit": {"type": "integer", "description": "Max messages.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "messages": {"type": "array"}},
+)
+def get_slack_channel_history(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "slack", "get_channel_history",
+        channel=input_data["channel"], limit=input_data.get("limit", 50),
+    )
+
+
+@action(
+    name="list_slack_users",
+    description="List users in the Slack workspace.",
+    action_sets=["slack"],
+    input_schema={
+        "limit": {"type": "integer", "description": "Max users to return.", "example": 100},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}, "users": {"type": "array"}},
+)
+def list_slack_users(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("slack", "list_users", limit=input_data.get("limit", 100))
+
+
+@action(
+    name="search_slack_messages",
+    description="Search for messages in the Slack workspace.",
+    action_sets=["slack"],
+    input_schema={
+        "query": {"type": "string", "description": "Search query.", "example": "project update"},
+        "count": {"type": "integer", "description": "Max results.", "example": 20},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def search_slack_messages(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "slack", "search_messages",
+        query=input_data["query"], count=input_data.get("count", 20),
+    )
+
+
+@action(
+    name="upload_slack_file",
+    description="Upload a file to a Slack channel.",
+    action_sets=["slack"],
+    input_schema={
+        "channels": {"type": "string", "description": "Channel ID to upload to.", "example": "C01234567"},
+        "file_path": {"type": "string", "description": "Local file path to upload.", "example": "/path/to/file.txt"},
+        "title": {"type": "string", "description": "File title.", "example": "Report"},
+        "initial_comment": {"type": "string", "description": "Message with the file.", "example": "Here's the report"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def upload_slack_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    channels = input_data["channels"]
+    if isinstance(channels, str):
+        channels = [channels]
+    return run_client_sync(
+        "slack", "upload_file",
+        channels=channels,
+        file_path=input_data.get("file_path"),
+        title=input_data.get("title"),
+        initial_comment=input_data.get("initial_comment"),
+    )
+
+
+@action(
+    name="get_slack_user_info",
+    description="Get info about a Slack user.",
+    action_sets=["slack"],
+    input_schema={
+        "slack_user_id": {"type": "string", "description": "User ID.", "example": "U1234567"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_slack_user_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("slack", "get_user_info", user_id=input_data["slack_user_id"])
+
+
+@action(
+    name="get_slack_channel_info",
+    description="Get info about a Slack channel.",
+    action_sets=["slack"],
+    input_schema={
+        "channel": {"type": "string", "description": "Channel ID.", "example": "C1234567"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def get_slack_channel_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("slack", "get_channel_info", channel=input_data["channel"])
+
+
+@action(
+    name="create_slack_channel",
+    description="Create a new Slack channel.",
+    action_sets=["slack"],
+    input_schema={
+        "name": {"type": "string", "description": "Channel name.", "example": "project-alpha"},
+        "is_private": {"type": "boolean", "description": "Is private?", "example": False},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def create_slack_channel(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "slack", "create_channel",
+        name=input_data["name"], is_private=input_data.get("is_private", False),
+    )
+
+
+@action(
+    name="invite_to_slack_channel",
+    description="Invite users to a Slack channel.",
+    action_sets=["slack"],
+    input_schema={
+        "channel": {"type": "string", "description": "Channel ID.", "example": "C1234567"},
+        "users": {"type": "array", "description": "List of user IDs.", "example": ["U123"]},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def invite_to_slack_channel(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync(
+        "slack", "invite_to_channel",
+        channel=input_data["channel"], users=input_data["users"],
+    )
+
+
+@action(
+    name="open_slack_dm",
+    description="Open a DM with Slack users.",
+    action_sets=["slack"],
+    input_schema={
+        "users": {"type": "array", "description": "List of user IDs.", "example": ["U123"]},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+def open_slack_dm(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client_sync
+    return run_client_sync("slack", "open_dm", users=input_data["users"])
diff --git a/app/data/action/integrations/telegram/telegram_actions.py b/app/data/action/integrations/telegram/telegram_actions.py
new file mode 100644
index 00000000..56a98af7
--- /dev/null
+++ b/app/data/action/integrations/telegram/telegram_actions.py
@@ -0,0 +1,277 @@
+from agent_core import action
+
+
+# =====================================================================
+# Bot API actions
+# =====================================================================
+
+@action(
+    name="send_telegram_bot_message",
+    description="Send a text message to a Telegram chat via bot. Use this ONLY when replying to Telegram Bot messages.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Telegram chat ID or @username.", "example": "123456789"},
+        "text": {"type": "string", "description": "Message text to send.", "example": "Hello!"},
+        "parse_mode": {"type": "string", "description": "Optional parse mode: HTML or Markdown.", "example": "HTML"},
+    },
+    output_schema={
+        "status": {"type": "string", "example": "success"},
+        "message": {"type": "string", "example": "Message sent"},
+    },
+)
+async def send_telegram_bot_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import record_outgoing_message, run_client
+    record_outgoing_message("Telegram", input_data["chat_id"], input_data["text"])
+    return await run_client(
+        "telegram_bot", "send_message",
+        recipient=input_data["chat_id"],
+        text=input_data["text"],
+        parse_mode=input_data.get("parse_mode"),
+    )
+
+
+@action(
+    name="send_telegram_photo",
+    description="Send a photo to a Telegram chat via bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Telegram chat ID.", "example": "123456789"},
+        "photo": {"type": "string", "description": "URL or file_id of the photo.", "example": "https://example.com/photo.jpg"},
+        "caption": {"type": "string", "description": "Optional photo caption.", "example": "Check this out"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_telegram_photo(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_bot", "send_photo",
+        chat_id=input_data["chat_id"],
+        photo=input_data["photo"],
+        caption=input_data.get("caption"),
+    )
+
+
+@action(
+    name="get_telegram_updates",
+    description="Get incoming updates (messages) for the Telegram bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "limit": {"type": "integer", "description": "Max number of updates to retrieve.", "example": 10},
+        "offset": {"type": "integer", "description": "Update offset for pagination.", "example": 0},
+    },
+    output_schema={
+        "status": {"type": "string", "example": "success"},
+        "updates": {"type": "array", "description": "List of update objects."},
+    },
+)
+async def get_telegram_updates(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_bot", "get_updates",
+        offset=input_data.get("offset"),
+        limit=input_data.get("limit", 100),
+    )
+
+
+@action(
+    name="get_telegram_chat",
+    description="Get information about a Telegram chat via bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Chat ID or @username.", "example": "123456789"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_telegram_chat(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("telegram_bot", "get_chat", chat_id=input_data["chat_id"])
+
+
+@action(
+    name="search_telegram_contact",
+    description="Search for a Telegram contact by name from bot's recent chat history.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "name": {"type": "string", "description": "Contact name to search for.", "example": "John"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def search_telegram_contact(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("telegram_bot", "search_contact", name=input_data["name"])
+
+
+@action(
+    name="send_telegram_document",
+    description="Send a document to a Telegram chat via bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
+        "document": {"type": "string", "description": "File ID or URL.", "example": "https://example.com/doc.pdf"},
+        "caption": {"type": "string", "description": "Caption.", "example": "Here is the file"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_telegram_document(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_bot", "send_document",
+        chat_id=input_data["chat_id"],
+        document=input_data["document"],
+        caption=input_data.get("caption"),
+    )
+
+
+@action(
+    name="forward_telegram_message",
+    description="Forward a message via bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Dest Chat ID.", "example": "123"},
+        "from_chat_id": {"type": "string", "description": "Source Chat ID.", "example": "456"},
+        "message_id": {"type": "integer", "description": "Message ID.", "example": 1},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def forward_telegram_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_bot", "forward_message",
+        chat_id=input_data["chat_id"],
+        from_chat_id=input_data["from_chat_id"],
+        message_id=input_data["message_id"],
+    )
+
+
+@action(
+    name="get_telegram_bot_info",
+    description="Get bot info.",
+    action_sets=["telegram_bot"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_telegram_bot_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("telegram_bot", "get_me")
+
+
+@action(
+    name="get_telegram_chat_members_count",
+    description="Get chat members count via bot.",
+    action_sets=["telegram_bot"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_telegram_chat_members_count(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_bot", "get_chat_members_count", chat_id=input_data["chat_id"],
+    )
+
+
+# =====================================================================
+# MTProto (user account) actions
+# =====================================================================
+
+@action(
+    name="get_telegram_chats",
+    description="Get chats via Telegram user account.",
+    action_sets=["telegram_user"],
+    input_schema={
+        "limit": {"type": "integer", "description": "Limit.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_telegram_chats(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_user", "get_dialogs", limit=input_data.get("limit", 50),
+    )
+
+
+@action(
+    name="read_telegram_messages",
+    description="Read messages via Telegram user account.",
+    action_sets=["telegram_user"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
+        "limit": {"type": "integer", "description": "Limit.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def read_telegram_messages(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_user", "get_messages",
+        chat_id=input_data["chat_id"],
+        limit=input_data.get("limit", 50),
+    )
+
+
+@action(
+    name="send_telegram_user_message",
+    description="Send a text message via Telegram user account. IMPORTANT: Use @username (e.g., '@emadtavana7') NOT numeric ID. Use 'self' or 'user' to message the owner's Saved Messages.",
+    action_sets=["telegram_user"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Recipient: @username (preferred), phone number, or 'self' for Saved Messages. Do NOT use numeric IDs.", "example": "@emadtavana7"},
+        "text": {"type": "string", "description": "Text.", "example": "Hi"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_telegram_user_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import record_outgoing_message, run_client
+    record_outgoing_message("Telegram", input_data["chat_id"], input_data["text"])
+    return await run_client(
+        "telegram_user", "send_message",
+        recipient=input_data["chat_id"],
+        text=input_data["text"],
+    )
+
+
+@action(
+    name="send_telegram_user_file",
+    description="Send a file via Telegram user account.",
+    action_sets=["telegram_user"],
+    input_schema={
+        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
+        "file_path": {"type": "string", "description": "Path.", "example": "/path/to/file"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_telegram_user_file(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_user", "send_file",
+        chat_id=input_data["chat_id"],
+        file_path=input_data["file_path"],
+    )
+
+
+@action(
+    name="search_telegram_user_contacts",
+    description="Search contacts via Telegram user account.",
+    action_sets=["telegram_user"],
+    input_schema={
+        "query": {"type": "string", "description": "Query.", "example": "John"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def search_telegram_user_contacts(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "telegram_user", "search_contacts", query=input_data["query"],
+    )
+
+
+@action(
+    name="get_telegram_user_account_info",
+    description="Get account info via Telegram user account.",
+    action_sets=["telegram_user"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_telegram_user_account_info(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("telegram_user", "get_me")
diff --git a/app/data/action/twitter/twitter_actions.py b/app/data/action/integrations/twitter/twitter_actions.py
similarity index 53%
rename from app/data/action/twitter/twitter_actions.py
rename to app/data/action/integrations/twitter/twitter_actions.py
index 909e4b3c..2688ef80 100644
--- a/app/data/action/twitter/twitter_actions.py
+++ b/app/data/action/integrations/twitter/twitter_actions.py
@@ -1,9 +1,6 @@
 from agent_core import action
 
 
-_NO_CRED_MSG = "No Twitter/X credential. Use /twitter login first."
-
-
 @action(
     name="post_tweet",
     description="Post a tweet on Twitter/X.",
@@ -16,15 +13,12 @@
     parallelizable=False,
 )
 async def post_tweet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.post_tweet(input_data["text"], reply_to=input_data.get("reply_to") or None)
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "twitter", "post_tweet",
+        text=input_data["text"],
+        reply_to=input_data.get("reply_to") or None,
+    )
 
 
 @action(
@@ -39,15 +33,11 @@ async def post_tweet(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def reply_to_tweet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.reply_to_tweet(input_data["tweet_id"], input_data["text"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "twitter",
+        lambda c: c.reply_to_tweet(input_data["tweet_id"], input_data["text"]),
+    )
 
 
 @action(
@@ -61,15 +51,8 @@ async def reply_to_tweet(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def delete_tweet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.delete_tweet(input_data["tweet_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("twitter", "delete_tweet", tweet_id=input_data["tweet_id"])
 
 
 @action(
@@ -83,15 +66,11 @@ async def delete_tweet(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def search_tweets(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.search_tweets(input_data["query"], max_results=input_data.get("max_results", 10))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import with_client
+    return await with_client(
+        "twitter",
+        lambda c: c.search_tweets(input_data["query"], max_results=input_data.get("max_results", 10)),
+    )
 
 
 @action(
@@ -105,18 +84,12 @@ async def search_tweets(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_twitter_timeline(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_user_timeline(
-            user_id=input_data.get("user_id") or None,
-            max_results=input_data.get("max_results", 10),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "twitter", "get_user_timeline",
+        user_id=input_data.get("user_id") or None,
+        max_results=input_data.get("max_results", 10),
+    )
 
 
 @action(
@@ -130,15 +103,8 @@ async def get_twitter_timeline(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def like_tweet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.like_tweet(input_data["tweet_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("twitter", "like_tweet", tweet_id=input_data["tweet_id"])
 
 
 @action(
@@ -152,15 +118,8 @@ async def like_tweet(input_data: dict) -> dict:
     parallelizable=False,
 )
 async def retweet(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.retweet(input_data["tweet_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("twitter", "retweet", tweet_id=input_data["tweet_id"])
 
 
 @action(
@@ -173,15 +132,8 @@ async def retweet(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_twitter_user(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_user_by_username(input_data["username"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("twitter", "get_user_by_username", username=input_data["username"])
 
 
 @action(
@@ -192,19 +144,12 @@ async def get_twitter_user(input_data: dict) -> dict:
     output_schema={"status": {"type": "string", "example": "success"}},
 )
 async def get_twitter_me(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
-        result = await client.get_me()
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("twitter", "get_me")
 
 
 # ------------------------------------------------------------------
-# Watch Settings
+# Watch Settings (custom: bespoke success messages, no async)
 # ------------------------------------------------------------------
 
 @action(
@@ -219,10 +164,10 @@ async def get_twitter_me(input_data: dict) -> dict:
 )
 def set_twitter_watch_tag(input_data: dict) -> dict:
     try:
-        from app.external_comms.platforms.twitter import TwitterClient
-        client = TwitterClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": _NO_CRED_MSG}
+        from craftos_integrations import get_client
+        client = get_client("twitter")
+        if not client or not client.has_credentials():
+            return {"status": "error", "message": "No Twitter/X credential. Use /twitter login first."}
         tag = input_data.get("tag", "").strip()
         client.set_watch_tag(tag)
         if tag:
diff --git a/app/data/action/integrations/whatsapp/whatsapp_actions.py b/app/data/action/integrations/whatsapp/whatsapp_actions.py
new file mode 100644
index 00000000..e0f8655e
--- /dev/null
+++ b/app/data/action/integrations/whatsapp/whatsapp_actions.py
@@ -0,0 +1,100 @@
+from agent_core import action
+
+
+@action(
+    name="send_whatsapp_web_text_message",
+    description="Send a text message via WhatsApp Web.",
+    action_sets=["whatsapp"],
+    input_schema={
+        "to": {"type": "string", "description": "Recipient phone number (e.g. '1234567890') OR the exact `number` / `id` value returned by search_whatsapp_contact (e.g. '185628603977847@lid'). Pass the value verbatim — do NOT strip the '@lid' or '@c.us' suffix.", "example": "1234567890"},
+        "message": {"type": "string", "description": "Message text.", "example": "Hello!"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_whatsapp_web_text_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import record_outgoing_message, run_client
+    # Record to conversation history BEFORE sending (ensures correct ordering)
+    record_outgoing_message("WhatsApp", input_data["to"], input_data["message"])
+    return await run_client(
+        "whatsapp_web", "send_message",
+        recipient=input_data["to"],
+        text=input_data["message"],
+    )
+
+
+@action(
+    name="send_whatsapp_web_media_message",
+    description="Send a media message via WhatsApp Web.",
+    action_sets=["whatsapp"],
+    input_schema={
+        "to": {"type": "string", "description": "Recipient phone number (e.g. '1234567890') OR the exact `number` / `id` value returned by search_whatsapp_contact (e.g. '185628603977847@lid'). Pass the value verbatim — do NOT strip the '@lid' or '@c.us' suffix.", "example": "1234567890"},
+        "media_path": {"type": "string", "description": "Local media path.", "example": "/path/to/img.jpg"},
+        "caption": {"type": "string", "description": "Optional caption.", "example": "Caption"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def send_whatsapp_web_media_message(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "whatsapp_web", "send_media",
+        recipient=input_data["to"],
+        media_path=input_data["media_path"],
+        caption=input_data.get("caption"),
+    )
+
+
+@action(
+    name="get_whatsapp_chat_history",
+    description="Get chat history (WhatsApp Web).",
+    action_sets=["whatsapp"],
+    input_schema={
+        "phone_number": {"type": "string", "description": "Phone number.", "example": "1234567890"},
+        "limit": {"type": "integer", "description": "Limit.", "example": 50},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_whatsapp_chat_history(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client(
+        "whatsapp_web", "get_chat_messages",
+        phone_number=input_data["phone_number"],
+        limit=input_data.get("limit", 50),
+    )
+
+
+@action(
+    name="get_whatsapp_unread_chats",
+    description="Get unread chats (WhatsApp Web).",
+    action_sets=["whatsapp"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_whatsapp_unread_chats(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("whatsapp_web", "get_unread_chats")
+
+
+@action(
+    name="search_whatsapp_contact",
+    description="Search contact by name (WhatsApp Web).",
+    action_sets=["whatsapp"],
+    input_schema={
+        "name": {"type": "string", "description": "Contact name.", "example": "John Doe"},
+    },
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def search_whatsapp_contact(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("whatsapp_web", "search_contact", name=input_data["name"])
+
+
+@action(
+    name="get_whatsapp_web_session_status",
+    description="Get WhatsApp Web session status.",
+    action_sets=["whatsapp"],
+    input_schema={},
+    output_schema={"status": {"type": "string", "example": "success"}},
+)
+async def get_whatsapp_web_session_status(input_data: dict) -> dict:
+    from app.data.action.integrations._helpers import run_client
+    return await run_client("whatsapp_web", "get_session_status")
diff --git a/app/data/action/linkedin/linkedin_actions.py b/app/data/action/linkedin/linkedin_actions.py
deleted file mode 100644
index 71b388a0..00000000
--- a/app/data/action/linkedin/linkedin_actions.py
+++ /dev/null
@@ -1,650 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="get_linkedin_profile",
-    description="Get the authenticated user's LinkedIn profile.",
-    action_sets=["linkedin"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_profile(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_user_profile()
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="create_linkedin_post",
-    description="Create a text post on LinkedIn.",
-    action_sets=["linkedin"],
-    input_schema={
-        "text": {"type": "string", "description": "Post text (max 3000 chars).", "example": "Excited to share..."},
-        "visibility": {"type": "string", "description": "Visibility: PUBLIC, CONNECTIONS, or LOGGED_IN.", "example": "PUBLIC"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def create_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.create_text_post(
-            person_urn, input_data["text"], visibility=input_data.get("visibility", "PUBLIC")
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_linkedin_jobs",
-    description="Search for job postings on LinkedIn.",
-    action_sets=["linkedin"],
-    input_schema={
-        "keywords": {"type": "string", "description": "Job search keywords.", "example": "software engineer"},
-        "location": {"type": "string", "description": "Optional location filter.", "example": ""},
-        "count": {"type": "integer", "description": "Number of results.", "example": 25},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def search_linkedin_jobs(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.search_jobs(
-            input_data["keywords"],
-            location=input_data.get("location"),
-            count=input_data.get("count", 25),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_connections",
-    description="Get the authenticated user's LinkedIn connections.",
-    action_sets=["linkedin"],
-    input_schema={
-        "count": {"type": "integer", "description": "Number of connections to return.", "example": 50},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_connections(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_connections(count=input_data.get("count", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_linkedin_message",
-    description="Send a message to LinkedIn users.",
-    action_sets=["linkedin"],
-    input_schema={
-        "recipient_urns": {"type": "array", "description": "List of recipient URNs (urn:li:person:xxx).", "example": []},
-        "subject": {"type": "string", "description": "Message subject.", "example": "Hello"},
-        "body": {"type": "string", "description": "Message body.", "example": "Hi, I wanted to connect..."},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def send_linkedin_message(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.send_message_to_recipients(
-            person_urn, input_data["recipient_urns"], input_data["subject"], input_data["body"]
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="delete_linkedin_post",
-    description="Delete a LinkedIn post.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def delete_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.delete_post(input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_organizations",
-    description="Get user's organizations.",
-    action_sets=["linkedin"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_organizations(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_my_organizations()
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_organization_info",
-    description="Get organization info.",
-    action_sets=["linkedin"],
-    input_schema={"organization_id": {"type": "string", "description": "Org ID.", "example": "123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_organization_info(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_organization(input_data["organization_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_organization_analytics",
-    description="Get organization analytics.",
-    action_sets=["linkedin"],
-    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_organization_analytics(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_organization_analytics(input_data["organization_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_job_details",
-    description="Get job details.",
-    action_sets=["linkedin"],
-    input_schema={"job_id": {"type": "string", "description": "Job ID.", "example": "123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_job_details(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_job_details(input_data["job_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_linkedin_connection_request",
-    description="Send connection request.",
-    action_sets=["linkedin"],
-    input_schema={
-        "invitee_profile_urn": {"type": "string", "description": "Profile URN.", "example": "urn:li:person:123"},
-        "message": {"type": "string", "description": "Message.", "example": "Hi"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def send_linkedin_connection_request(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.send_connection_request(
-            input_data["invitee_profile_urn"], message=input_data.get("message")
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_sent_invitations",
-    description="Get sent invitations.",
-    action_sets=["linkedin"],
-    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_sent_invitations(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_sent_invitations(count=input_data.get("count", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_received_invitations",
-    description="Get received invitations.",
-    action_sets=["linkedin"],
-    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_received_invitations(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_received_invitations(count=input_data.get("count", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="respond_to_linkedin_invitation",
-    description="Respond to invitation.",
-    action_sets=["linkedin"],
-    input_schema={
-        "invitation_urn": {"type": "string", "description": "Invitation URN.", "example": "urn:li:invitation:123"},
-        "action": {"type": "string", "description": "accept/ignore.", "example": "accept"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def respond_to_linkedin_invitation(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.respond_to_invitation(input_data["invitation_urn"], input_data["action"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="like_linkedin_post",
-    description="Like a post.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def like_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.like_post(person_urn, input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="unlike_linkedin_post",
-    description="Unlike a post.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def unlike_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.unlike_post(person_urn, input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_post_likes",
-    description="Get post likes.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_post_likes(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_post_reactions(input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="comment_on_linkedin_post",
-    description="Comment on a post.",
-    action_sets=["linkedin"],
-    input_schema={
-        "post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"},
-        "text": {"type": "string", "description": "Comment text.", "example": "Great post!"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def comment_on_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.comment_on_post(person_urn, input_data["post_urn"], input_data["text"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_post_comments",
-    description="Get post comments.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_post_comments(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_post_comments(input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="delete_linkedin_comment",
-    description="Delete a comment.",
-    action_sets=["linkedin"],
-    input_schema={
-        "post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"},
-        "comment_urn": {"type": "string", "description": "Comment URN.", "example": "urn:li:comment:123"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def delete_linkedin_comment(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.delete_comment(person_urn, input_data["post_urn"], input_data["comment_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_my_linkedin_posts",
-    description="Get my posts.",
-    action_sets=["linkedin"],
-    input_schema={"count": {"type": "integer", "description": "Count.", "example": 50}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_my_linkedin_posts(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.get_posts_by_author(person_urn, count=input_data.get("count", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_organization_posts",
-    description="Get organization posts.",
-    action_sets=["linkedin"],
-    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_organization_posts(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_posts_by_author(input_data["organization_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_post",
-    description="Get a post.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_post(input_data["post_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="reshare_linkedin_post",
-    description="Reshare a post.",
-    action_sets=["linkedin"],
-    input_schema={
-        "original_post_urn": {"type": "string", "description": "Original Post URN.", "example": "urn:li:share:123"},
-        "commentary": {"type": "string", "description": "Commentary.", "example": "Interesting!"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def reshare_linkedin_post(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.reshare_post(
-            person_urn, input_data["original_post_urn"], commentary=input_data.get("commentary", "")
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_linkedin_companies",
-    description="Search companies.",
-    action_sets=["linkedin"],
-    input_schema={"keywords": {"type": "string", "description": "Keywords.", "example": "tech"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def search_linkedin_companies(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.search_companies(input_data["keywords"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="lookup_linkedin_company",
-    description="Lookup company by vanity name.",
-    action_sets=["linkedin"],
-    input_schema={"vanity_name": {"type": "string", "description": "Vanity name.", "example": "microsoft"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def lookup_linkedin_company(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_company_by_vanity_name(input_data["vanity_name"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_person",
-    description="Get person profile by ID.",
-    action_sets=["linkedin"],
-    input_schema={"person_id": {"type": "string", "description": "Person ID.", "example": "123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_person(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_person(input_data["person_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_conversations",
-    description="Get conversations.",
-    action_sets=["linkedin"],
-    input_schema={"count": {"type": "integer", "description": "Count.", "example": 20}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_conversations(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_conversations(count=input_data.get("count", 20))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_linkedin_post_analytics",
-    description="Get post analytics.",
-    action_sets=["linkedin"],
-    input_schema={"post_urn": {"type": "string", "description": "Post URN.", "example": "urn:li:share:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_linkedin_post_analytics(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        result = client.get_post_analytics([input_data["post_urn"]])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="follow_linkedin_organization",
-    description="Follow organization.",
-    action_sets=["linkedin"],
-    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def follow_linkedin_organization(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.follow_organization(person_urn, input_data["organization_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="unfollow_linkedin_organization",
-    description="Unfollow organization.",
-    action_sets=["linkedin"],
-    input_schema={"organization_urn": {"type": "string", "description": "Org URN.", "example": "urn:li:organization:123"}},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def unfollow_linkedin_organization(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.linkedin import LinkedInClient
-        client = LinkedInClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No LinkedIn credential. Use /linkedin login first."}
-        cred = client._load()
-        person_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else f"urn:li:person:{cred.user_id}"
-        result = client.unfollow_organization(person_urn, input_data["organization_urn"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/living_ui_actions.py b/app/data/action/living_ui_actions.py
index 1c3c28e5..243935de 100644
--- a/app/data/action/living_ui_actions.py
+++ b/app/data/action/living_ui_actions.py
@@ -543,6 +543,17 @@ def living_ui_http(input_data: dict) -> dict:
         }
         if parsed_json is not None:
             out["response_json"] = parsed_json
+
+        # If the agent just mutated the Living UI's data, tell the browser so the
+        # iframe reloads to show fresh state. The frontend debounces these so a
+        # burst of writes only triggers one reload.
+        if resp.ok and method in {"POST", "PUT", "PATCH", "DELETE"}:
+            try:
+                from app.living_ui import dispatch_living_ui_data_changed
+                dispatch_living_ui_data_changed(project_id)
+            except Exception:
+                pass
+
         return out
     except Exception as e:
         return {"status": "error", "status_code": 0, "response_headers": {}, "body": "", "final_url": url, "elapsed_ms": 0, "message": str(e)}
diff --git a/app/data/action/outlook/outlook_actions.py b/app/data/action/outlook/outlook_actions.py
deleted file mode 100644
index 06b4f376..00000000
--- a/app/data/action/outlook/outlook_actions.py
+++ /dev/null
@@ -1,153 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="send_outlook_email",
-    description="Send an email via Outlook (Microsoft 365).",
-    action_sets=["outlook"],
-    input_schema={
-        "to": {"type": "string", "description": "Recipient email address.", "example": "user@example.com"},
-        "subject": {"type": "string", "description": "Email subject.", "example": "Meeting Follow-up"},
-        "body": {"type": "string", "description": "Email body text.", "example": "Hi, here are the notes..."},
-        "cc": {"type": "string", "description": "Optional CC recipients (comma-separated).", "example": ""},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def send_outlook_email(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.send_email(
-            to=input_data["to"],
-            subject=input_data["subject"],
-            body=input_data["body"],
-            cc=input_data.get("cc"),
-        )
-        if result.get("ok"):
-            return {"status": "success", "message": "Email sent."}
-        return {"status": "error", "message": result.get("error", "Failed to send email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="list_outlook_emails",
-    description="List recent emails from Outlook inbox.",
-    action_sets=["outlook"],
-    input_schema={
-        "count": {"type": "integer", "description": "Number of recent emails to list.", "example": 10},
-        "unread_only": {"type": "boolean", "description": "Only show unread emails.", "example": False},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def list_outlook_emails(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.list_emails(
-            n=input_data.get("count", 10),
-            unread_only=input_data.get("unread_only", False),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to list emails.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_outlook_email",
-    description="Get full details of a specific Outlook email by message ID.",
-    action_sets=["outlook"],
-    input_schema={
-        "message_id": {"type": "string", "description": "Outlook message ID.", "example": "AAMk..."},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_outlook_email(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.get_email(message_id=input_data["message_id"])
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to get email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="read_top_outlook_emails",
-    description="Read the top N recent Outlook emails with details.",
-    action_sets=["outlook"],
-    input_schema={
-        "count": {"type": "integer", "description": "Number of emails to read.", "example": 5},
-        "full_body": {"type": "boolean", "description": "Include full body text.", "example": False},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def read_top_outlook_emails(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.read_top_emails(
-            n=input_data.get("count", 5),
-            full_body=input_data.get("full_body", False),
-        )
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to read emails.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="mark_outlook_email_read",
-    description="Mark an Outlook email as read.",
-    action_sets=["outlook"],
-    input_schema={
-        "message_id": {"type": "string", "description": "Outlook message ID.", "example": "AAMk..."},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def mark_outlook_email_read(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.mark_as_read(message_id=input_data["message_id"])
-        if result.get("ok"):
-            return {"status": "success", "message": "Email marked as read."}
-        return {"status": "error", "message": result.get("error", "Failed to mark email.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="list_outlook_folders",
-    description="List mail folders in Outlook.",
-    action_sets=["outlook"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def list_outlook_folders(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.outlook import OutlookClient
-        client = OutlookClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Outlook credential. Use /outlook login first."}
-        result = client.list_folders()
-        if result.get("ok"):
-            return {"status": "success", "result": result["result"]}
-        return {"status": "error", "message": result.get("error", "Failed to list folders.")}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/slack/slack_actions.py b/app/data/action/slack/slack_actions.py
deleted file mode 100644
index de81740a..00000000
--- a/app/data/action/slack/slack_actions.py
+++ /dev/null
@@ -1,253 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="send_slack_message",
-    description="Send a message to a Slack channel or DM.",
-    action_sets=["slack"],
-    input_schema={
-        "channel": {"type": "string", "description": "Channel ID or name.", "example": "C01234567"},
-        "text": {"type": "string", "description": "Message text.", "example": "Hello team!"},
-        "thread_ts": {"type": "string", "description": "Optional thread timestamp for replies.", "example": ""},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_slack_message(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = await client.send_message(
-            input_data["channel"],
-            input_data["text"],
-            thread_ts=input_data.get("thread_ts"),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="list_slack_channels",
-    description="List channels in the Slack workspace.",
-    action_sets=["slack"],
-    input_schema={
-        "limit": {"type": "integer", "description": "Max channels to return.", "example": 100},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}, "channels": {"type": "array"}},
-)
-def list_slack_channels(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.list_channels(limit=input_data.get("limit", 100))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_slack_channel_history",
-    description="Get message history from a Slack channel.",
-    action_sets=["slack"],
-    input_schema={
-        "channel": {"type": "string", "description": "Channel ID.", "example": "C01234567"},
-        "limit": {"type": "integer", "description": "Max messages.", "example": 50},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}, "messages": {"type": "array"}},
-)
-def get_slack_channel_history(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.get_channel_history(input_data["channel"], limit=input_data.get("limit", 50))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="list_slack_users",
-    description="List users in the Slack workspace.",
-    action_sets=["slack"],
-    input_schema={
-        "limit": {"type": "integer", "description": "Max users to return.", "example": 100},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}, "users": {"type": "array"}},
-)
-def list_slack_users(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.list_users(limit=input_data.get("limit", 100))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_slack_messages",
-    description="Search for messages in the Slack workspace.",
-    action_sets=["slack"],
-    input_schema={
-        "query": {"type": "string", "description": "Search query.", "example": "project update"},
-        "count": {"type": "integer", "description": "Max results.", "example": 20},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def search_slack_messages(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.search_messages(input_data["query"], count=input_data.get("count", 20))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="upload_slack_file",
-    description="Upload a file to a Slack channel.",
-    action_sets=["slack"],
-    input_schema={
-        "channels": {"type": "string", "description": "Channel ID to upload to.", "example": "C01234567"},
-        "file_path": {"type": "string", "description": "Local file path to upload.", "example": "/path/to/file.txt"},
-        "title": {"type": "string", "description": "File title.", "example": "Report"},
-        "initial_comment": {"type": "string", "description": "Message with the file.", "example": "Here's the report"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def upload_slack_file(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        channels = input_data["channels"]
-        if isinstance(channels, str):
-            channels = [channels]
-        result = client.upload_file(
-            channels,
-            file_path=input_data.get("file_path"),
-            title=input_data.get("title"),
-            initial_comment=input_data.get("initial_comment"),
-        )
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_slack_user_info",
-    description="Get info about a Slack user.",
-    action_sets=["slack"],
-    input_schema={
-        "slack_user_id": {"type": "string", "description": "User ID.", "example": "U1234567"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_slack_user_info(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.get_user_info(input_data["slack_user_id"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_slack_channel_info",
-    description="Get info about a Slack channel.",
-    action_sets=["slack"],
-    input_schema={
-        "channel": {"type": "string", "description": "Channel ID.", "example": "C1234567"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def get_slack_channel_info(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.get_channel_info(input_data["channel"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="create_slack_channel",
-    description="Create a new Slack channel.",
-    action_sets=["slack"],
-    input_schema={
-        "name": {"type": "string", "description": "Channel name.", "example": "project-alpha"},
-        "is_private": {"type": "boolean", "description": "Is private?", "example": False},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def create_slack_channel(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.create_channel(input_data["name"], is_private=input_data.get("is_private", False))
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="invite_to_slack_channel",
-    description="Invite users to a Slack channel.",
-    action_sets=["slack"],
-    input_schema={
-        "channel": {"type": "string", "description": "Channel ID.", "example": "C1234567"},
-        "users": {"type": "array", "description": "List of user IDs.", "example": ["U123"]},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def invite_to_slack_channel(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.invite_to_channel(input_data["channel"], input_data["users"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="open_slack_dm",
-    description="Open a DM with Slack users.",
-    action_sets=["slack"],
-    input_schema={
-        "users": {"type": "array", "description": "List of user IDs.", "example": ["U123"]},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-def open_slack_dm(input_data: dict) -> dict:
-    try:
-        from app.external_comms.platforms.slack import SlackClient
-        client = SlackClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Slack credential. Use /slack login first."}
-        result = client.open_dm(input_data["users"])
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/telegram/telegram_actions.py b/app/data/action/telegram/telegram_actions.py
deleted file mode 100644
index 5b3f6b5e..00000000
--- a/app/data/action/telegram/telegram_actions.py
+++ /dev/null
@@ -1,430 +0,0 @@
-from agent_core import action
-
-
-# =====================================================================
-# Bot API actions
-# =====================================================================
-
-
-@action(
-    name="send_telegram_bot_message",
-    description="Send a text message to a Telegram chat via bot. Use this ONLY when replying to Telegram Bot messages.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Telegram chat ID or @username.", "example": "123456789"},
-        "text": {"type": "string", "description": "Message text to send.", "example": "Hello!"},
-        "parse_mode": {"type": "string", "description": "Optional parse mode: HTML or Markdown.", "example": "HTML"},
-    },
-    output_schema={
-        "status": {"type": "string", "example": "success"},
-        "message": {"type": "string", "example": "Message sent"},
-    },
-)
-async def send_telegram_bot_message(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("telegram_bot")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        # Record to conversation history before sending
-        try:
-            import app.internal_action_interface as iai
-            sm = iai.InternalActionInterface.state_manager
-            if sm:
-                sm.event_stream_manager.record_conversation_message(
-                    "agent message to platform: Telegram",
-                    f"[Sent via Telegram to {input_data['chat_id']}]: {input_data['text']}",
-                )
-                sm._append_to_conversation_history(
-                    "agent",
-                    f"[Sent via Telegram to {input_data['chat_id']}]: {input_data['text']}",
-                )
-        except Exception:
-            pass
-        result = await client.send_message(
-            input_data["chat_id"],
-            input_data["text"],
-            parse_mode=input_data.get("parse_mode"),
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_telegram_photo",
-    description="Send a photo to a Telegram chat via bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Telegram chat ID.", "example": "123456789"},
-        "photo": {"type": "string", "description": "URL or file_id of the photo.", "example": "https://example.com/photo.jpg"},
-        "caption": {"type": "string", "description": "Optional photo caption.", "example": "Check this out"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_telegram_photo(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.send_photo(
-            input_data["chat_id"],
-            input_data["photo"],
-            caption=input_data.get("caption"),
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_telegram_updates",
-    description="Get incoming updates (messages) for the Telegram bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "limit": {"type": "integer", "description": "Max number of updates to retrieve.", "example": 10},
-        "offset": {"type": "integer", "description": "Update offset for pagination.", "example": 0},
-    },
-    output_schema={
-        "status": {"type": "string", "example": "success"},
-        "updates": {"type": "array", "description": "List of update objects."},
-    },
-)
-async def get_telegram_updates(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.get_updates(
-            offset=input_data.get("offset"),
-            limit=input_data.get("limit", 100),
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_telegram_chat",
-    description="Get information about a Telegram chat via bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Chat ID or @username.", "example": "123456789"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_telegram_chat(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.get_chat(input_data["chat_id"])
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_telegram_contact",
-    description="Search for a Telegram contact by name from bot's recent chat history.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "name": {"type": "string", "description": "Contact name to search for.", "example": "John"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def search_telegram_contact(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.search_contact(input_data["name"])
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_telegram_document",
-    description="Send a document to a Telegram chat via bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
-        "document": {"type": "string", "description": "File ID or URL.", "example": "https://example.com/doc.pdf"},
-        "caption": {"type": "string", "description": "Caption.", "example": "Here is the file"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_telegram_document(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.send_document(
-            input_data["chat_id"],
-            input_data["document"],
-            caption=input_data.get("caption"),
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="forward_telegram_message",
-    description="Forward a message via bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Dest Chat ID.", "example": "123"},
-        "from_chat_id": {"type": "string", "description": "Source Chat ID.", "example": "456"},
-        "message_id": {"type": "integer", "description": "Message ID.", "example": 1},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def forward_telegram_message(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.forward_message(
-            input_data["chat_id"],
-            input_data["from_chat_id"],
-            input_data["message_id"],
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_telegram_bot_info",
-    description="Get bot info.",
-    action_sets=["telegram_bot"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_telegram_bot_info(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.get_me()
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_telegram_chat_members_count",
-    description="Get chat members count via bot.",
-    action_sets=["telegram_bot"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_telegram_chat_members_count(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_bot import TelegramBotClient
-    try:
-        client = TelegramBotClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram bot credential. Use /telegram login first."}
-        result = await client.get_chat_members_count(input_data["chat_id"])
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-# =====================================================================
-# MTProto actions
-# =====================================================================
-
-
-@action(
-    name="get_telegram_chats",
-    description="Get chats via Telegram user account.",
-    action_sets=["telegram_user"],
-    input_schema={
-        "limit": {"type": "integer", "description": "Limit.", "example": 50},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_telegram_chats(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_user import TelegramUserClient
-    try:
-        client = TelegramUserClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        result = await client.get_dialogs(limit=input_data.get("limit", 50))
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="read_telegram_messages",
-    description="Read messages via Telegram user account.",
-    action_sets=["telegram_user"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
-        "limit": {"type": "integer", "description": "Limit.", "example": 50},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def read_telegram_messages(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_user import TelegramUserClient
-    try:
-        client = TelegramUserClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        result = await client.get_messages(
-            input_data["chat_id"],
-            limit=input_data.get("limit", 50),
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_telegram_user_message",
-    description="Send a text message via Telegram user account. IMPORTANT: Use @username (e.g., '@emadtavana7') NOT numeric ID. Use 'self' or 'user' to message the owner's Saved Messages.",
-    action_sets=["telegram_user"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Recipient: @username (preferred), phone number, or 'self' for Saved Messages. Do NOT use numeric IDs.", "example": "@emadtavana7"},
-        "text": {"type": "string", "description": "Text.", "example": "Hi"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_telegram_user_message(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("telegram_user")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        # Record to conversation history before sending
-        try:
-            import app.internal_action_interface as iai
-            sm = iai.InternalActionInterface.state_manager
-            if sm:
-                sm.event_stream_manager.record_conversation_message(
-                    "agent message to platform: Telegram",
-                    f"[Sent via Telegram to {input_data['chat_id']}]: {input_data['text']}",
-                )
-                sm._append_to_conversation_history(
-                    "agent",
-                    f"[Sent via Telegram to {input_data['chat_id']}]: {input_data['text']}",
-                )
-        except Exception:
-            pass
-        result = await client.send_message(
-            input_data["chat_id"],
-            input_data["text"],
-        )
-        if result is None:
-            return {"status": "error", "message": "No response from Telegram client"}
-        if isinstance(result, dict) and "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_telegram_user_file",
-    description="Send a file via Telegram user account.",
-    action_sets=["telegram_user"],
-    input_schema={
-        "chat_id": {"type": "string", "description": "Chat ID.", "example": "123"},
-        "file_path": {"type": "string", "description": "Path.", "example": "/path/to/file"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_telegram_user_file(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_user import TelegramUserClient
-    try:
-        client = TelegramUserClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        result = await client.send_file(
-            input_data["chat_id"],
-            input_data["file_path"],
-        )
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_telegram_user_contacts",
-    description="Search contacts via Telegram user account.",
-    action_sets=["telegram_user"],
-    input_schema={
-        "query": {"type": "string", "description": "Query.", "example": "John"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def search_telegram_user_contacts(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_user import TelegramUserClient
-    try:
-        client = TelegramUserClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        result = await client.search_contacts(input_data["query"])
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_telegram_user_account_info",
-    description="Get account info via Telegram user account.",
-    action_sets=["telegram_user"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_telegram_user_account_info(input_data: dict) -> dict:
-    from app.external_comms.platforms.telegram_user import TelegramUserClient
-    try:
-        client = TelegramUserClient()
-        if not client.has_credentials():
-            return {"status": "error", "message": "No Telegram user credential. Use /telegram login first."}
-        result = await client.get_me()
-        if "error" in result:
-            return {"status": "error", "message": result["error"]}
-        return {"status": "success", "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/action/understand_video.py b/app/data/action/understand_video.py
index 10f5cc71..fdf21468 100644
--- a/app/data/action/understand_video.py
+++ b/app/data/action/understand_video.py
@@ -5,7 +5,7 @@
     description="Uses the configured VLM model (default: Gemini 1.5 Pro) for native video understanding when a Google API key is configured. Falls back to keyframe extraction via OpenCV if no Google API key is available.",
     mode="CLI",
     action_sets=["document_processing", "image", "video"],
-    requirement=["google-generativeai"],
+    requirement=["google-genai"],
     input_schema={
         "video_path": {
             "type": "string",
@@ -88,7 +88,7 @@ def understand_video(input_data: dict) -> dict:
 # delegating entirely to InternalActionInterface. The reason is architectural:
 #
 # PATH 1 — Gemini Native (below, runs when api_key is present):
-#   Uses the Gemini Files API (genai.upload_file) for true native video
+#   Uses the Gemini Files API (client.files.upload) for true native video
 #   understanding. The full video is uploaded and processed by the model with
 #   temporal context — no frame sampling needed. The uploaded file is deleted
 #   from Gemini servers after the call. The full summary is saved to disk.
@@ -105,25 +105,27 @@ def understand_video(input_data: dict) -> dict:
 
     if api_key:
         try:
-            import google.generativeai as genai
-            genai.configure(api_key=api_key)
+            from google import genai
+            client = genai.Client(api_key=api_key)
             import time
             from datetime import datetime
             from app.config import AGENT_WORKSPACE_ROOT
 
-            video_file = genai.upload_file(path=video_path)
-            
+            video_file = client.files.upload(file=video_path)
+
             while video_file.state.name == "PROCESSING":
                 time.sleep(2)
-                video_file = genai.get_file(video_file.name)
-                
+                video_file = client.files.get(name=video_file.name)
+
             vlm_model = get_vlm_model() or "gemini-1.5-pro"
-            model = genai.GenerativeModel(vlm_model)
             prompt = query if query else "Understand and describe the contents of this video."
-            response = model.generate_content([video_file, prompt])
-            
-            genai.delete_file(video_file.name)
-            
+            response = client.models.generate_content(
+                model=vlm_model,
+                contents=[video_file, prompt],
+            )
+
+            client.files.delete(name=video_file.name)
+
             full_text = response.text
             ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
             out_path = os.path.join(AGENT_WORKSPACE_ROOT, f"video_summary_{ts}.txt")
diff --git a/app/data/action/whatsapp/whatsapp_actions.py b/app/data/action/whatsapp/whatsapp_actions.py
deleted file mode 100644
index b6e07980..00000000
--- a/app/data/action/whatsapp/whatsapp_actions.py
+++ /dev/null
@@ -1,153 +0,0 @@
-from agent_core import action
-
-
-@action(
-    name="send_whatsapp_web_text_message",
-    description="Send a text message via WhatsApp Web.",
-    action_sets=["whatsapp"],
-    input_schema={
-        "to": {"type": "string", "description": "Recipient phone number.", "example": "1234567890"},
-        "message": {"type": "string", "description": "Message text.", "example": "Hello!"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_whatsapp_web_text_message(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        # Record to conversation history BEFORE sending (ensures correct ordering)
-        try:
-            import app.internal_action_interface as iai
-            sm = iai.InternalActionInterface.state_manager
-            if sm:
-                sm.event_stream_manager.record_conversation_message(
-                    "agent message to platform: WhatsApp",
-                    f"[Sent via WhatsApp to {input_data['to']}]: {input_data['message']}",
-                )
-                sm._append_to_conversation_history(
-                    "agent",
-                    f"[Sent via WhatsApp to {input_data['to']}]: {input_data['message']}",
-                )
-        except Exception as e:
-            import logging
-            logging.getLogger(__name__).warning(f"[WA-Action] Failed to record conversation: {e}")
-        result = await client.send_message(
-            recipient=input_data["to"],
-            text=input_data["message"],
-        )
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="send_whatsapp_web_media_message",
-    description="Send a media message via WhatsApp Web.",
-    action_sets=["whatsapp"],
-    input_schema={
-        "to": {"type": "string", "description": "Recipient phone number.", "example": "1234567890"},
-        "media_path": {"type": "string", "description": "Local media path.", "example": "/path/to/img.jpg"},
-        "caption": {"type": "string", "description": "Optional caption.", "example": "Caption"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def send_whatsapp_web_media_message(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        result = await client.send_media(
-            recipient=input_data["to"],
-            media_path=input_data["media_path"],
-            caption=input_data.get("caption"),
-        )
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_whatsapp_chat_history",
-    description="Get chat history (WhatsApp Web).",
-    action_sets=["whatsapp"],
-    input_schema={
-        "phone_number": {"type": "string", "description": "Phone number.", "example": "1234567890"},
-        "limit": {"type": "integer", "description": "Limit.", "example": 50},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_whatsapp_chat_history(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        result = await client.get_chat_messages(
-            phone_number=input_data["phone_number"],
-            limit=input_data.get("limit", 50),
-        )
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_whatsapp_unread_chats",
-    description="Get unread chats (WhatsApp Web).",
-    action_sets=["whatsapp"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_whatsapp_unread_chats(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        result = await client.get_unread_chats()
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="search_whatsapp_contact",
-    description="Search contact by name (WhatsApp Web).",
-    action_sets=["whatsapp"],
-    input_schema={
-        "name": {"type": "string", "description": "Contact name.", "example": "John Doe"},
-    },
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def search_whatsapp_contact(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        result = await client.search_contact(name=input_data["name"])
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
-
-
-@action(
-    name="get_whatsapp_web_session_status",
-    description="Get WhatsApp Web session status.",
-    action_sets=["whatsapp"],
-    input_schema={},
-    output_schema={"status": {"type": "string", "example": "success"}},
-)
-async def get_whatsapp_web_session_status(input_data: dict) -> dict:
-    from app.external_comms.registry import get_client
-    try:
-        client = get_client("whatsapp_web")
-        if not client or not client.has_credentials():
-            return {"status": "error", "message": "No WhatsApp credential. Please log into whatsapp first."}
-        result = await client.get_session_status()
-        return {"status": result.get("status", "success"), "result": result}
-    except Exception as e:
-        return {"status": "error", "message": str(e)}
diff --git a/app/data/agent_file_system_template/AGENT.md b/app/data/agent_file_system_template/AGENT.md
index 910a24a6..9e88863b 100644
--- a/app/data/agent_file_system_template/AGENT.md
+++ b/app/data/agent_file_system_template/AGENT.md
@@ -1,152 +1,4538 @@
-# Agent Identity
-
-You are a general-purpose personal assistant AI agent developed by CraftOS.
-Your primary role is to assist users with ANY computer-based tasks. You can execute commands, manipulate files, browse the web, interact with applications, and complete complex multi-step workflows autonomously.
-You are not a chatbot. You are an autonomous agent that takes actions to accomplish goals. When given a task, you plan, execute, validate, and iterate until the goal is achieved or you determine it cannot be completed.
-
-## Error Handling
-
-Errors are normal. How you handle them determines success.
-- When an action fails, first understand why. Check the error message and the event stream. Is it a temporary issue that might succeed on retry? Is it a fundamental problem with your approach? Is it something outside your control?
-- For temporary failures (network issues, timing problems), a retry may work. But do not retry blindly - wait a moment, or try with slightly different parameters.
-- For approach failures (wrong action, incorrect parameters, misunderstanding of the task), change your approach. Select a different action or reformulate your plan.
-- For impossible tasks (required access you do not have, physical actions needed, policy violations), stop and inform the user. Explain what you tried, why it cannot work, and suggest alternatives if any exist.
-- If you find yourself stuck in a loop - the same action failing repeatedly with the same error - recognize this pattern and break out. Either try a fundamentally different approach or inform the user that you are blocked.
-- Never continue executing actions indefinitely when they are not making progress. This wastes resources and frustrates users.
-
-## File Handling
-
-Efficient File Reading:
-- read_file returns content with line numbers (cat -n format)
-- Default limit is 2000 lines - check has_more in response to know if file continues
-- For large files (>500 lines), follow this strategy:
-  1. Read beginning first to understand structure
-  2. Use grep_files to find specific patterns/functions
-  3. Use read_file with offset/limit to read targeted sections based on grep results
-
-File Actions:
-- read_file: General reading with pagination (offset/limit)
-- grep_files: Search files/directories for regex patterns with three output modes: 'files_with_matches' (discover files), 'content' (matching lines with line numbers), 'count' (match counts). Supports glob/file_type filtering, before/after context lines, case_insensitive, and multiline.
-- stream_read + stream_edit: Use together for file modifications
-
-Avoid: Reading entire large files repeatedly - use grep + targeted offset/limit reads instead
-
-## Self-Improvement Protocol
-
-You are a self-improving agent. When you encounter a capability gap, proactively expand your abilities using the following mechanisms.
-
-### Self-Improvement Workflow
-When you CANNOT complete a task due to missing capabilities:
-1. IDENTIFY - What capability is missing?
-2. SEARCH - Use `web_search` to find MCP servers or skills that provide the capability
-3. INSTALL - Edit config files or clone repositories to install the solution
-4. WAIT - The system will automatically detect the file change and hot-reload the new capability
-5. CONTINUE - Proceed with the task using the new capability
-6. REMEMBER - Store the solution in memory for future reference
-
-IMPORTANT: Always inform the user when you install new capabilities. Ask for permission if the installation requires credentials or has security implications.
-
-### Automatic Hot-Reload
-All configuration files are monitored for changes. When you edit any config file, the system automatically detects the change and reloads the configuration within ~1 second. No manual reload actions or restart required.
-
-Monitored config files:
-- `app/config/settings.json` - Settings (API keys, model config, OAuth credentials)
-- `app/config/mcp_config.json` - MCP server connections
-- `app/config/skills_config.json` - Skill configurations
-- `app/config/external_comms_config.json` - Communication platform integrations
-
-### 1. MCP - Install New Tools
-Config file: `app/config/mcp_config.json`
-
-When you lack a capability (e.g., cannot access a service, need a specific tool):
-1. Use `read_file` to check existing MCP servers in `app/config/mcp_config.json`
-2. Use `web_search` to find MCP servers: search "<capability> MCP server" or "modelcontextprotocol <service>"
-3. Use `stream_edit` to add new server entry to the `mcp_servers` array in `app/config/mcp_config.json`
-4. Set `"enabled": true` to activate the server
-5. The system will automatically detect the change and connect to the new server
-
-MCP server entry format:
-```json
-{
-  "name": "server-name",
-  "description": "What this server does",
-  "transport": "stdio",
-  "command": "npx",
-  "args": ["-y", "@org/server-package"],
-  "env": {"API_KEY": ""},
-  "enabled": true
+---
+version: 3
+purpose: agent operations manual
+---
+
+# AGENT.md
+
+Your ops manual. Grep `## <topic>` to load what you need.
+
+## Index
+
+<!-- index -->
+```
+add MCP server          → ## MCP
+add skill               → ## Skills
+connect platform        → ## Integrations
+use an integration      → ## Integrations  (and grep its INTEGRATION.md)
+switch model            → ## Models
+set API key             → ## Models
+generate document       → ## Documents
+build Living UI         → ## Living UI
+schedule recurring task → ## Proactive
+edit config file        → ## Configs
+start a task            → ## Tasks
+handle an error         → ## Errors
+read / edit a file      → ## Files
+discover an action      → ## Actions
+persistent storage      → ## File System
+long-running work       → ## Workspace
+self-improve            → ## Self-Improvement
+edit AGENT/USER/SOUL.md → ## Self-Edit
+look up a term          → ## Glossary
+```
+<!-- /index -->
+
+---
+
+## Runtime
+
+You run inside `AgentBase.react(trigger)` at [app/agent_base.py](app/agent_base.py). Each turn: one trigger is consumed, the LLM picks one or more actions, the executor runs them, events are appended to streams, and (often) a new trigger is queued for the next turn.
+
+### Trigger anatomy
+
+Triggers live in a priority queue at [agent_core/core/impl/trigger/queue.py](agent_core/core/impl/trigger/queue.py), ordered by `fire_at` (Unix timestamp) then `priority` (lower number = higher priority). Each trigger carries:
+
+```
+fire_at:                  float    when it should fire
+priority:                 int      ordering within same fire_at
+next_action_description:  str      human-readable hint
+payload:                  dict     routing + context
+session_id:               str|None which session/task this belongs to
+waiting_for_reply:        bool     paused for user input
+```
+
+`payload.type` is the routing key:
+```
+"memory_processing"   → memory workflow      (creates a memory-processor task)
+"proactive_heartbeat" → proactive heartbeat  (creates a Heartbeat task)
+"proactive_planner"   → proactive planner    (creates a day/week/month planner task)
+<absent or other>     → falls through to task / conversation routing by session state
+```
+
+Trigger producers:
+- The scheduler ([app/config/scheduler_config.json](app/config/scheduler_config.json)) — fires `memory_processing`, `proactive_heartbeat`, `proactive_planner` on cron.
+- External-comms listeners and the UI — fire triggers carrying user messages in the payload.
+- Actions you invoke — `wait`, `task_end`, and others enqueue follow-up triggers via `triggers.put(...)`.
+
+### react() routing (in order)
+
+```
+1.  _is_memory_trigger(trigger)        → _handle_memory_workflow         → return
+2.  _is_proactive_trigger(trigger)     → _handle_proactive_workflow      → return
+3.  _extract_trigger_data(trigger)
+4.  _initialize_session(...)
+5.  record user_message in trigger payload (if any) into the event stream
+6.  if active task is waiting_for_user_reply AND no user_message arrived
+        → re-queue the trigger with a 3-hour delay → return
+7.  _is_complex_task_mode(session)     → _handle_complex_task_workflow
+8.  _is_simple_task_mode(session)      → _handle_simple_task_workflow
+9.  default                            → _handle_conversation_workflow
+```
+
+Steps 7-9 share the same shape: `_select_action` (LLM picks actions; session caching for cache hits) → `_retrieve_and_prepare_actions` → `_execute_actions` → `_finalize_action_execution`. The differences are session state, todo handling, and caching strategy.
+
+### Workflows
+
+**memory** — `_handle_memory_workflow`
+- Trigger source: scheduler `memory-processing` (daily 3am) or startup replay if EVENT_UNPROCESSED.md is non-empty.
+- Behavior: spawns a task that uses the `memory-processor` skill. The task reads EVENT_UNPROCESSED.md, scores events, distills important ones into MEMORY.md, clears the buffer. May also prune MEMORY.md if `max_items` is exceeded.
+- During this task, `event_stream_manager.set_skip_unprocessed_logging(True)` is on, so the task's own events do not loop back into EVENT_UNPROCESSED.md. Reset on `task_end`.
+- Skipped entirely if `is_memory_enabled()` is False.
+- See `## Memory`.
+
+**proactive heartbeat** — `_handle_proactive_heartbeat`
+- Trigger source: scheduler `heartbeat` (cron `0,30 * * * *`).
+- Behavior: `proactive_manager.get_all_due_tasks()` collects due recurring tasks across all frequencies. If none, returns silently. Otherwise creates one `Heartbeat` task: `mode=simple`, `action_sets=[file_operations, proactive, web_research]`, `skill=heartbeat-processor`.
+- Skipped entirely if `is_proactive_enabled()` is False.
+- See `## Proactive`.
+
+**proactive planner** — `_handle_proactive_planner`
+- Trigger source: scheduler `day-planner` (daily 7am), `week-planner` (Sun 5pm), `month-planner` (1st 8am).
+- Behavior: creates a task named `<Day|Week|Month> Planner`, mode=simple, action_sets=[file_operations, proactive], skill=`<scope>-planner`. Task instruction: review recent interactions and update the Goals/Plan/Status section of PROACTIVE.md.
+
+**complex task** — `_handle_complex_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == False`.
+- Full todo state machine; user-approval gate at the end. Session caching enabled for multi-turn efficiency. Parallel action execution supported.
+- See `## Tasks` for the full lifecycle.
+
+**simple task** — `_handle_simple_task_workflow`
+- Active when a task exists for the session and `task.is_simple_task() == True`.
+- Same select→prepare→execute→finalize flow as complex; no todos; auto-ends. Session caching enabled.
+
+**conversation** — `_handle_conversation_workflow`
+- Active when no task is running for the session.
+- Same flow as simple/complex but uses prefix caching only (no session cache). Supports parallel `task_start` to launch multiple tasks at once.
+- If the executed actions return a `task_id`, the session adopts that task and subsequent triggers route to the task workflow.
+
+### Re-entry and waiting
+
+Calling `wait` or having a task in `waiting_for_user_reply` does not block the loop — it queues a trigger with `fire_at` in the future. When that trigger fires:
+- If the wait was for a user reply and one arrived → process normally.
+- If no user message arrived but the task is still flagged `waiting_for_user_reply` → react re-queues the trigger with a fresh 3-hour delay and returns. The agent silently waits without consuming context.
+
+### Components attached at construction
+
+You do not call these directly, but every action routes through them. Knowing what owns what helps you debug:
+
+```
+LLMInterface           text + vision generation gateway
+ActionLibrary          DB-backed action storage (atomic + divisible)
+ActionManager          action lifecycle
+ActionRouter           LLM-based action selection
+ActionExecutor         sandboxed (ephemeral venv) or internal execution
+TaskManager            task lifecycle, per-task event streams, session storage
+StateManager           session state, current_task_id, current_task
+ContextEngine          builds system + user prompt each turn (KV cache aware)
+MemoryManager          ChromaDB-backed RAG over agent_file_system
+EventStreamManager     appends to EVENT.md / EVENT_UNPROCESSED.md / per-task streams
+MCPClient              external MCP tool servers
+SkillManager           SKILL.md discovery + selection + reload
+Scheduler              cron-driven trigger fires from scheduler_config.json
+ProactiveManager       PROACTIVE.md registry + get_all_due_tasks()
+ExternalCommsManager   platform listeners + senders
+WorkflowLockManager    blocks concurrent memory / proactive runs
+```
+
+### Workflow locks
+
+[agent_core/core/impl/workflow_lock/manager.py](agent_core/core/impl/workflow_lock/manager.py) gates concurrent runs of background workflows. Lock names in use:
+
+```
+"memory_processing"        only one memory-processor task at a time
+"proactive_*"              one proactive workflow per scope at a time
+```
+
+If a trigger fires while its lock is held, the new trigger is dropped silently. The next scheduled fire will pick up the work. This is by design — do not work around it.
+
+### State and context every turn
+
+What the LLM sees on each `_select_action` call:
+- Static system prompt (your role, policy, file-system map, environment).
+- The relevant slice of the event stream (recent actions, results, user messages).
+- Memory pointers retrieved by the ContextEngine for relevance.
+- Current task state if a task is active (instruction, todos, action sets, skills selected).
+- The list of currently available actions (filtered by selected action sets and current mode).
+
+Knowing this shape helps you decide what context to enrich. Need history beyond what's in the stream? Use `memory_search` (`## Memory`) or read TASK_HISTORY.md / CONVERSATION_HISTORY.md directly (`## File System`).
+
+---
+
+## Tasks
+
+Three runtime modes route through this section: **conversation**, **simple**, **complex**. Each has a distinct purpose, action surface, and starting move.
+
+### Conversation mode
+
+Active when **no task is running** for the session. Default state when a user message arrives in a fresh session.
+
+Action surface in conversation mode is intentionally small ([agent_core/core/prompts/action.py](agent_core/core/prompts/action.py)):
+```
+task_start(...)        begin a task — THE way user requests become work
+send_message(...)      reply without starting a task
+ignore                 user input needs no reply (e.g. emoji-only ack)
+```
+
+You CANNOT call file ops, web search, MCP tools, integrations, or skills directly from conversation mode. To unlock them, start a task first.
+
+You MAY emit multiple `task_start` actions in parallel from a single conversation turn. Example: user says "research topic A and topic B" → two parallel `task_start` calls, one per topic.
+
+When to stay in conversation mode:
+- Greeting, small talk, clarifying question.
+- Acknowledging a user message that needs no work.
+- Routing decisions where the user must confirm before any task starts (e.g. "do you want me to delete X?").
+
+When to leave conversation mode (call `task_start`):
+- ANY request that needs file access, web, MCP, skills, integrations, or memory beyond what's in your current context.
+- Even if you "think" you know the answer — if the request is computer-based and could benefit from verification, start a task. Do not refuse a task by claiming a limitation without checking.
+
+### Starting a task: `task_start` vs `schedule_task`
+
+```
+From conversation (no active task)  →  task_start(task_name, task_description, task_mode)
+From inside a task (simple/complex) →  schedule_task(name, instruction, schedule="immediate", mode, ...)
+For later / recurring execution     →  schedule_task(name, instruction, schedule="<expr>", ...)
+```
+
+**`task_start` cannot be called from inside another task.** If you're mid-task and need to spawn a separate one, use `schedule_task` with `schedule="immediate"`. The two actions create equivalent task objects — the difference is the entry point.
+
+`schedule_task` schedule expressions (validated by [app/scheduler/parser.py](app/scheduler/parser.py)):
+```
+"immediate"               run right now (queues an immediate trigger)
+"at 3pm" / "at 3:30pm"    one-time today
+"tomorrow at 9am"         one-time tomorrow
+"in 2 hours" / "in 30 minutes"    one-time relative
+"every day at 7am"        recurring daily
+"every monday at 9am"     recurring weekly
+"every 3 hours"           recurring interval
+"0 7 * * *"               cron (5-field)
+```
+Times must include `am`/`pm`. Freeform like "daily at", "weekly", "every morning", "every weekday" are NOT accepted.
+
+One-time scheduled tasks are auto-removed after firing. Recurring schedules persist in [app/config/scheduler_config.json](app/config/scheduler_config.json).
+
+### Simple mode
+
+Use for work completable in 2-3 actions where no user approval is required at the end.
+
+Pick simple when:
+- Quick lookup (weather, time, exchange rate).
+- Single-answer question (calculation, conversion).
+- Search and summarize where the result is the response.
+- No file the user must review.
+- No irreversible external action (no sends, no payments, no destructive writes).
+
+Flow:
+```
+1. task_start(task_mode="simple", ...)            ← from conversation
+   OR schedule_task(mode="simple", schedule="immediate", ...)  ← from inside a task
+2. (optional) send_message — brief ack
+3. Execute the 1-3 actions
+4. send_message — deliver the result
+5. task_end                                       ← auto-completes, no approval gate
+```
+
+Simple-mode rules:
+- No `task_update_todos`. No phase prefixes. The work is small enough that planning would slow you down.
+- Session caching IS active during simple-mode multi-turn execution (cache hits across the 2-3 turns).
+- If during execution you discover the work is bigger than simple — STOP. End the simple task with the partial result via `send_message` + `task_end`. Then `schedule_task(schedule="immediate", mode="complex")` for the remainder. Do NOT silently chain more actions in simple mode.
+
+### Complex mode
+
+Use for multi-step work, file outputs, irreversible operations, anything the user calls a "project", or anything spanning multiple sessions.
+
+Pick complex when:
+- Plan has more than 3 actions.
+- Output is a file or artifact the user should review and approve.
+- Work touches external state (sends messages, makes purchases, modifies third-party data).
+- Work spans multiple sessions or days (mission-scale — see `## Workspace`).
+
+State machine:
+```
+task_start(task_mode="complex", ...)             ← from conversation
+   OR schedule_task(mode="complex", schedule="immediate", ...)  ← from inside a task
+       │
+       ▼
+send_message                                      ← acknowledge IMMEDIATELY
+       │
+       ▼
+task_update_todos(<full plan, all "pending", phase-prefixed>)
+       │
+       ▼
+loop {
+    mark ONE todo "in_progress"
+    execute relevant actions (parallel within the same todo is fine)
+    mark that todo "completed"
+    if you discover missing info → add a fresh "Collect:" todo, revert
 }
+       │
+       ▼
+send_message(<final result + explicit approval request>)
+       │
+       ▼
+wait for user reply  ← queues a future trigger; you do NOT block, see ## Runtime
+       │
+       ▼
+task_end                                          ← only after explicit approval
 ```
 
-Common patterns:
-- NPX packages: `"command": "npx", "args": ["-y", "@modelcontextprotocol/server-name"]`
-- Python servers: `"command": "uv", "args": ["run", "--directory", "/path/to/server", "main.py"]`
-- HTTP/SSE servers: `"transport": "sse", "url": "http://localhost:3000/mcp"`
-
-### 2. Skill - Install Workflows and Instructions
-Config file: `app/config/skills_config.json`
-Skills directory: `skills/`
-
-When you need specialized workflows or domain knowledge:
-1. Use `read_file` to check `app/config/skills_config.json` for existing skills
-2. Use `web_search` to find skills: search "SKILL.md <domain>" or "<capability> agent skill github"
-3. Use `run_shell` to clone the skill repository into the `skills/` directory:
-   `git clone https://github.com/user/skill-repo skills/skill-name`
-4. Use `stream_edit` to add the skill name to `enabled_skills` array in `app/config/skills_config.json`
-5. The system will automatically detect the change and load the new skill
-
-### 3. App - Configure Integrations
-Config file: `app/config/external_comms_config.json`
-
-When you need to connect to communication platforms:
-1. Use `read_file` to check current config in `app/config/external_comms_config.json`
-2. Use `stream_edit` to update the platform configuration:
-   - Set required credentials (bot_token, api_key, phone_number, etc.)
-   - Set `"enabled": true` to activate
-3. The system will automatically detect the change and start/stop platform connections
-
-Supported platforms:
-- Telegram: bot mode (bot_token) or user mode (api_id, api_hash, phone_number)
-- WhatsApp: web mode (session_id) or API mode (phone_number_id, access_token)
-
-### 4. Model & API Keys - Configure Providers
-Config file: `app/config/settings.json`
-
-When you need different model capabilities or need to set API keys:
-1. Use `read_file` to check current settings in `app/config/settings.json`
-2. If the target model has no API key, you MUST ask the user for one. Without a valid API key, all LLM requests will fail.
-3. Use `stream_edit` to update model configuration and/or API keys:
-```json
+### Todo phase prefixes (mandatory in complex mode)
+
+Every todo must begin with one of these prefixes:
+```
+Acknowledge:   Restate the user's goal in your own words
+Collect:       Gather inputs (read files, search, ask user, list integrations)
+Execute:       Do the work (generate, transform, send, write)
+Verify:        Check the output meets the goal (re-read files, run tests, smoke-test)
+Confirm:       Present the result to the user for approval
+Cleanup:       Remove temp files, restore state, close connections
+```
+
+Rules:
+- Exactly ONE todo `in_progress` at a time. Always.
+- Never skip Verify on todos that produce files or change external state.
+- Never reach Cleanup before Confirm has been signed off by the user.
+- If during Execute you discover missing info, add a new `Collect:` todo and revert. Do not guess.
+- Cleanup is also where you remove `workspace/tmp/{task_id}/` artifacts you do not want to persist (the directory is auto-cleaned anyway, but explicit cleanup catches files saved elsewhere).
+
+### Action sets and skills (locked at task start)
+
+When a task is created via `task_start` or `schedule_task`, action sets and skills are selected automatically by the LLM based on the task description ([app/internal_action_interface.py](app/internal_action_interface.py) `do_create_task`). If the task was started via a skill slash command (e.g. `/pdf`), the pre-selected skill bypasses LLM skill selection but action sets are still LLM-selected and merged with skill-recommended ones.
+
+Once the task starts, the selection is **locked**. Mid-task changes:
+- Action sets: `action_set_management` action can add/remove sets.
+- Skills: cannot be swapped mid-task. End the task and start a new one if you need a different skill.
+
+### Output destinations
+
+- Files the user should keep across sessions → `agent_file_system/workspace/`
+- Drafts, sketches, intermediate state → `agent_file_system/workspace/tmp/{task_id}/` (auto-cleaned on `task_end` and on agent start)
+- Mission-scale, multi-task initiatives → `agent_file_system/workspace/missions/<mission_name>/INDEX.md`
+
+See `## Workspace` for the mission template and scan-on-start protocol.
+
+### Common task-mode mistakes to avoid
+
+- Starting in **simple**, work grows mid-task → do NOT silently chain more actions. End simple, schedule complex.
+- Calling `task_start` **from inside a task** → it doesn't work that way. Use `schedule_task` instead.
+- Using `schedule_task("immediate")` **from conversation** → use `task_start`. Conversation is built around it; using `schedule_task` from conversation creates an extra trigger hop.
+- Calling `task_end` **without a final `send_message`** → simple tasks must deliver the result; complex tasks must summarize and request approval. Never end silently.
+- Marking todos `completed` **before the actions ran** → mark `in_progress`, run, then mark `completed`.
+- Adding planning todos like `Acknowledge: Plan the work` to simple tasks → simple tasks do not use todos at all.
+
+---
+
+## Communication Rules
+
+The user only sees what you send via `send_message` (or `send_message_with_attachment`). Everything else — actions, errors, internal reasoning — is invisible to them.
+
+Cadence:
+- **Acknowledge immediately** after `task_start`. One sentence is enough. Don't wait for the first action to complete.
+- **Update on milestones**, not on every action. A milestone is: phase transition (Collect → Execute), significant finding, blocker, request for input.
+- **Stay silent during tight Verify loops.** If you're re-reading a file three times to check formatting, do not narrate each read.
+- **Final message before `task_end`** must summarize what was done, list any artifacts (with paths), and explicitly request approval.
+
+Channel choice:
+- Default: in-context chat.
+- If the user has a `Preferred Messaging Platform` set in `USER.md` and the task is asynchronous (proactive task, scheduled completion), prefer that platform.
+- Use `send_message_with_attachment` when sending generated files; pass the workspace path.
+
+What NOT to send:
+- Internal reasoning ("I'm now thinking about...").
+- Tool-call narration ("Let me run grep_files...").
+- Repeated acknowledgements after the first.
+- Status pings during fast operations.
+
+Hard rules:
+- Never end a complex task without explicit approval.
+- Never end any task silently.
+- Never claim success when an action failed — see `## Errors`.
+
+---
+
+## Errors
+
+You operate inside a harness with multiple safety layers. Some failures are handled automatically; others require you to recover deliberately. Knowing which is which is the difference between a productive recovery and an infinite loop.
+
+### Action result schema (read this first)
+
+EVERY action — built-in, MCP-routed, or skill-spawned — returns a dict with at minimum:
+
+```
 {
-  "model": {
-    "llm_provider": "anthropic",
-    "vlm_provider": "anthropic",
-    "llm_model": "claude-sonnet-4-20250514",
-    "vlm_model": "claude-sonnet-4-20250514"
-  },
-  "api_keys": {
-    "openai": "sk-...",
-    "anthropic": "sk-ant-...",
-    "google": "...",
-    "byteplus": "..."
-  }
+  "status": "success" | "error",
+  "message": "<human-readable detail>",     # present on error, often present on success
+  ... action-specific output fields ...
 }
 ```
-4. The system will automatically detect the change and update settings (model changes take effect in new tasks)
 
-Available providers: openai, anthropic, gemini, byteplus, remote (Ollama)
+Before you treat an action's output as a result you can act on, **check `status`**. If `status == "error"`, the `message` field tells you what went wrong. Failing to check `status` and proceeding as if everything worked is the most common avoidable failure mode in this harness.
+
+### Error event kinds in the event stream
+
+The event stream ([agent_core/core/impl/event_stream/manager.py](agent_core/core/impl/event_stream/manager.py)) records errors in distinct event kinds. You will see these when reviewing your own past steps:
+
+```
+"error"          react-level errors. LLM failures, exceptions in workflow handlers.
+                 Display message comes from classify_llm_error() (see below).
+"action_error"   actions DROPPED before execution: parallel-constraint violations,
+                 missing actions, invalid decisions.
+                 (Distinct from an action that ran and returned status=error.)
+"warning"        soft warnings that you must heed:
+                 - Action limit at 80% / 100%
+                 - Token limit at 80% / 100%
+                 - Other harness alerts
+"internal"       limit-choice messages, system-side info.
+```
+
+When you see an `"error"` or `"action_error"` event in the stream, it has already been logged. You do NOT need to log it again. You DO need to react to it.
+
+### Harness-level safety nets (do not duplicate)
+
+The harness already handles certain failures so you do not have to. Recognizing them prevents you from stepping on the harness.
+
+**Per-action timeout** ([agent_core/core/impl/action/executor.py](agent_core/core/impl/action/executor.py))
+- Default `DEFAULT_ACTION_TIMEOUT = 6000` seconds (100 min). Individual actions may declare shorter timeouts.
+- On timeout, the action returns:
+  ```
+  {"status": "error", "message": "Execution timed out after Ns while running <internal|sandboxed> action."}
+  ```
+- Recovery: the timeout is final for that invocation. Either retry with smaller scope (fewer rows, narrower regex, smaller batch) or split the work into multiple actions.
+
+**LLM consecutive-failure circuit breaker** ([agent_core/core/impl/llm/errors.py](agent_core/core/impl/llm/errors.py), [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py))
+- After repeated consecutive LLM failures (auth, network, etc.), the harness raises `LLMConsecutiveFailureError`.
+- `_handle_react_error` walks the exception chain (`__cause__`/`__context__`) to detect this and **automatically cancels the task** via `task_manager.mark_task_cancel(...)`. The agent's last instruction is cached in `_llm_retry_instructions[session_id]` for retry-after-fix.
+- A `LLM_FATAL_ERROR` UI event is emitted so the user sees a clear failure dialog.
+- **Implication:** if you see `MSG_CONSECUTIVE_FAILURE` ("LLM calls have failed N consecutive times. Task aborted to prevent infinite retries."), the task is already gone. Do NOT try to re-create it. The user must check their LLM configuration.
+
+**Action limit (`max_actions_per_task`, minimum 5)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Tracked in `STATE.get_agent_property("action_count")` against `max_actions_per_task`.
+- At **80%** the harness logs a `"warning"` event:
+  > "Action limit nearing: 80% of the maximum actions (N actions) has been used. Consider wrapping up the task or informing the user that the task may be too complex. If necessary, mark the task as aborted to prevent premature termination."
+  - Your response: **wrap up**. Send the best result you have, or ask the user whether to abort. Do NOT ignore.
+- At **100%** the harness logs a `"warning"`, sends a Continue/Abort chat message to the user, and PAUSES the task. `_check_agent_limits` returns False; the next trigger does not get scheduled. The task resumes only when the user picks Continue (limits reset) or Abort.
+
+**Token limit (`max_tokens_per_task`, minimum 100000)** ([agent_core/core/state/types.py](agent_core/core/state/types.py))
+- Same 80% warning / 100% pause pattern as actions, but for cumulative token usage.
+- 80% warning text is identical except "tokens" instead of "actions".
+- 100% triggers the same Continue/Abort gate.
+- Your response at 80%: same as action warning — wrap up or summarize aggressively.
+
+**Parallel constraint violations**
+- The router may drop an action before it runs and surface a `"action_error"` event with `_error` describing the constraint (e.g., "ignore must run alone", "cannot run multiple send_message in parallel").
+- The action is not executed; subsequent actions in the same batch may still run.
+- Recovery: re-issue the action sequentially in the next turn, not in parallel.
+
+### LLM error classes (from `classify_llm_error`)
+
+When an LLM call fails non-fatally, `classify_llm_error()` returns one of these messages. Knowing the class tells you whether retrying makes sense and what to tell the user:
+
+```
+MSG_AUTH         (HTTP 401/403)   "Unable to connect to AI service. Check your API key in Settings."
+                                  → DO NOT retry. Tell user to set/fix API key. See ## Models.
+MSG_MODEL        (HTTP 404)       "The selected AI model is not available."
+                                  → DO NOT retry. Tell user model name is wrong/unavailable.
+MSG_CONFIG       (HTTP 400)       "AI service configuration error. The selected model may not support required features."
+                                  → DO NOT retry. May indicate a feature flag (vision, tool use) not supported by chosen model.
+MSG_RATE_LIMIT   (HTTP 429)       "AI service is rate-limited. Please wait a moment and try again."
+                                  → Retryable after delay. Consider enabling slow_mode in settings.
+MSG_SERVICE      (HTTP 5xx)       "AI service is temporarily unavailable. Please try again later."
+                                  → Retryable. Often transient.
+MSG_CONNECTION   (timeout, ConnectionError)  "Unable to reach AI service. Check your internet."
+                                  → Retryable if connectivity recovers.
+MSG_GENERIC      (unmatched)      "An error occurred with the AI service."
+                                  → Investigate before retrying.
+```
+
+These come back as user-friendly strings to display; the harness wraps them in `"error"` events. You see them via the event stream and `display_message`.
+
+### Failure taxonomy and recovery decision
+
+There are four failure types. Identify which one you are in, then follow the matching recovery.
+
+**TRANSIENT**
+- Symptoms: rate limit, transient 5xx, connection error, file lock, sandbox process hiccup.
+- Action: wait briefly, retry ONCE with the same params.
+- Budget: 1 retry per action invocation. No second retry on the same params.
+
+**APPROACH**
+- Symptoms: action returned `status=error` with a "bad params" / "not found" / "invalid format" message. Semantic mismatch (you grepped the wrong file, ran the wrong action).
+- Action: change the approach. Different action, different params, different plan. Do NOT retry the same call unchanged.
+- Examples:
+  - `read_file` on a non-existent path → `find_files` first.
+  - `schedule_task` with `"daily at 9am"` rejected → use `"every day at 9am"` (the validated format).
+
+**IMPOSSIBLE**
+- Symptoms: missing access (no API key, no integration), hardware action needed (physical printer), policy violation, user data the agent cannot access.
+- Action: stop. `send_message` explaining what was tried and why it cannot work. Offer alternatives if any. For complex tasks, mark the task aborted.
+- Examples:
+  - `/linkedin login` required → ask user to authenticate.
+  - "send a fax" → state limitation, suggest email.
+
+**LOOP**
+- Symptoms: same action + same params + same error TWICE.
+- Action: stop immediately. Escalate to user with a specific question. Do NOT try a third time.
+- Why: loops burn action/token budget and produce no progress. The harness's `max_actions_per_task` and `LLMConsecutiveFailureError` limits are backstops, not your primary safety.
+
+### Recovery patterns by error source
+
+**File / shell / Python action returns `status=error`**
+- Read the `message` field. It often points at the fix (file not found, permission, syntax error, missing dep).
+- If the message says missing dependency for `run_python` / `run_shell`, install it via `pip install`/`npm install` in a follow-up `run_shell` call (auto-installed in sandboxed mode for declared `requirements`, but ad-hoc imports require explicit install).
+- If it says path not found, `find_files` or `list_folder` to locate before retry.
+
+**Web / fetch action returns error**
+- HTTP 4xx → URL or auth wrong. Don't retry the same URL.
+- HTTP 5xx or timeout → transient. One retry, then fall back (different URL, cached source, or report unavailability).
+- Empty result on `web_search` → broaden query or try a different search term. Do NOT keep retrying the same query.
+
+**Schedule / proactive action returns error**
+- Schedule expression rejected by parser → see `## Tasks` for the validated format list. Re-issue with a supported expression.
+- Recurring task creation fails → check PROACTIVE.md for syntax errors near your edit; the file's HTML markers (`PROACTIVE_TASKS_START`/`END`) must remain intact.
+
+**MCP tool returns error**
+- Server-side error in the MCP tool → check EVENT.md for stderr from the MCP server process. Often missing API key in the server's `env` block.
+- Tool not found → server may be disabled in `mcp_config.json` or the `action_set_name` not loaded. See `## MCP`.
+
+**Action limit / token limit warning at 80%**
+- Wrap up. Send the partial result and ask the user whether to continue.
+- If the work genuinely needs more budget, ask the user explicitly — they can pick Continue at the 100% gate and the limits reset.
+- Marking the task as aborted (`task_end` with status=aborted/failed) is preferable to silently exceeding the limit and pausing the task.
+
+**Action limit / token limit reached (100%)**
+- The task is paused; you don't get a next trigger until the user chooses Continue or Abort.
+- Do NOT attempt to schedule anything or send messages — the harness has already sent the user a Continue/Abort dialog.
+- When the user picks Continue, your next trigger arrives with limits reset.
+
+**LLM call failed (non-fatal)**
+- The harness retries internally up to its consecutive-failure threshold.
+- If you see a `"error"` event with one of the `MSG_*` strings, treat it according to the class table above.
+- If it escalates to `LLMConsecutiveFailureError` (`MSG_CONSECUTIVE_FAILURE`), the task is already cancelled. Do not try to recreate it.
+
+### Self-troubleshooting via logs
+
+When the action's `status=error` message does not tell you enough to recover, drop down to the runtime logs. The agent harness writes everything it does to disk, and you can read it.
+
+**Three log surfaces. Know which to use for what.**
+
+```
+EVENT.md                       agent_file_system/EVENT.md
+                               your perspective: events you produced/observed
+                               (action_start, action_end, send_message, error,
+                               warning, action_error, internal). Already on disk
+                               and indexed by memory_search.
+
+logs/<timestamp>.log           project_root/logs/
+                               runtime perspective: harness internals, every
+                               subsystem's INFO/WARN/ERROR log line. Loguru
+                               format. Rotates at 50 MB, kept 14 days.
+                               This is where stderr from sandboxed actions,
+                               MCP server output, and Python tracebacks land.
+
+diagnostic/logs/actions/       diagnostic/logs/actions/<ts>_<slug>.log.json
+                               per-action diagnostic dump (when run via the
+                               diagnostic harness). Contains full input/output
+                               for individual actions. See diagnostic/README.md.
+```
+
+**Picking the right surface:**
+- "What did I do, and what did the harness say back?" → EVENT.md.
+- "Why did this action / MCP / hot-reload actually fail?" → `logs/<timestamp>.log`.
+- "I want to replay one specific action's full input/output" → `diagnostic/logs/actions/`.
+
+**Log line format (loguru):**
+```
+2026-05-03 16:00:12.066 | INFO     | agent_core.core.database_interface:__init__:60 - Action registry loaded. 195 actions...
+^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+timestamp                  level      module:function:line                          message
+```
+- Levels: `DEBUG` < `INFO` < `WARNING` < `ERROR`. Default file threshold is INFO; harness emits a lot at INFO, so most context is captured.
+- The `module:function:line` segment tells you exactly where in the codebase the message came from. You can `read_file <module path>` and jump to the line for full context.
+
+**Subsystem tags you will see in messages.** Most subsystems prefix their log lines with a bracketed tag — grep for these:
+
+```
+[REACT]            react loop main flow                       app/agent_base.py
+[REACT ERROR]      react-level exceptions caught              app/agent_base.py:_handle_react_error
+[ACTION]           action preparation and execution           app/agent_base.py:_execute_actions
+[TASK]             task lifecycle (create, update, end)       agent_core/core/impl/task/manager.py
+[MEMORY]           memory indexing and processing             agent_core/core/impl/memory/manager.py
+[MCP]              MCP server init, connect, tool calls       agent_core/core/impl/mcp/client.py
+[SETTINGS]         settings load and updates                  agent_core/core/impl/settings/manager.py
+[CONFIG_WATCHER]   hot-reload events                          agent_core/core/impl/config/watcher.py
+[LIMIT]            action/token limit choice messages         app/agent_base.py
+[SESSION]          session cache lifecycle                    agent_core/core/impl/llm/interface.py
+[STATE]            state-debug snapshots                      app/agent_base.py
+[ONBOARDING]       onboarding state                           agent_core/core/impl/onboarding/manager.py
+[PROACTIVE]        proactive workflow                         app/proactive/manager.py
+[RESTORE]          startup task restoration                   app/agent_base.py:_restore_sessions
+[AGENT]            agent init, mode toggles                   app/agent_base.py:__init__
+[LLM FACTORY]      LLM provider construction                  agent_core/core/impl/llm/interface.py
+```
+
+**Self-troubleshooting workflow.** When an action returns an error you cannot decode from `message` alone:
+
+```
+1. Identify the latest log file:
+     list_folder logs/                        ← logs are timestamped, latest is freshest
+2. Find the time window of the failure:
+     - From EVENT.md, note the timestamp of the failing event.
+     - That same timestamp will exist in logs/<latest>.log (within seconds).
+3. Grep around that time + the relevant subsystem tag:
+     grep_files "[MCP]"   logs/<latest>.log -A 5 -B 1   ← MCP server failure?
+     grep_files "[ACTION]" logs/<latest>.log -A 5 -B 1   ← action execution issue?
+     grep_files "ERROR"    logs/<latest>.log -B 2 -A 10  ← any error-level line + context
+4. If a Python traceback is present, read upward from the traceback to the
+   most recent INFO line in the same subsystem — that tells you the last
+   successful step before the failure.
+5. The "module:function:line" field on the failing log line points at the code
+   path. read_file <module path> with offset = line - 30 to inspect.
+6. Decide:
+     - The error is in your action params       → ## Errors / APPROACH
+     - The error is in a subsystem (MCP server crash, settings parse error,
+       hot-reload exception)                   → ## MCP / ## Configs / ## Hot Reload
+     - The error is in the LLM call             → see classify_llm_error classes above
+     - The error is environmental (no API key,
+       missing dep, port in use)               → tell the user, do not retry blindly
+```
+
+**Concrete grep recipes:**
+
+```
+# Did an MCP server crash on startup or fail to connect?
+grep_files "[MCP]" logs/<latest>.log -A 3
+# → look for "Failed to connect", "subprocess exited", non-zero return codes.
+
+# Did the config watcher fail to apply a hot reload?
+grep_files "[CONFIG_WATCHER]" logs/<latest>.log -A 3
+
+# Did settings.json fail to parse?
+grep_files "[SETTINGS]" logs/<latest>.log -A 3
+
+# Did an action time out, and which one?
+grep_files "Execution timed out" logs/<latest>.log -B 5
+
+# Did the LLM hit consecutive failures?
+grep_files "LLMConsecutiveFailureError\|MSG_CONSECUTIVE_FAILURE" logs/<latest>.log -A 5
+
+# Did a sandboxed action subprocess produce stderr?
+grep_files "venv\|requirements\|subprocess" logs/<latest>.log -A 3
+
+# What did the agent's _check_agent_limits last log?
+grep_files "[LIMIT]" logs/<latest>.log -A 2
+
+# When did the last task end, and how?
+grep_files "[TASK].*ended\|task_end\|mark_task_cancel" logs/<latest>.log -A 3
+
+# Find the last 100 ERROR-level lines across the whole log:
+grep_files "| ERROR " logs/<latest>.log -A 5
+```
+
+**Acting on what you find.** A log line is data, not a fix. The decision rules:
+
+```
+If the log shows                               then
+─────────────────────────────────────────────  ──────────────────────────────────────
+[MCP] subprocess exited with code N            MCP server crashed. Inspect its env in
+                                               mcp_config.json. Likely missing API
+                                               key or wrong command path. See ## MCP.
+
+[SETTINGS] JSONDecodeError                     settings.json is malformed. Read the
+                                               file, find the syntax error around the
+                                               reported line, fix via stream_edit.
+
+[CONFIG_WATCHER] reload failed                 the change was not picked up. Save
+                                               again, or check the file is tracked in
+                                               watcher.register() (see ## Hot Reload).
+
+[REACT ERROR] LLMConsecutiveFailureError       harness already cancelled the task.
+                                               Tell user to fix LLM config. Do NOT
+                                               retry. See ## Models.
+
+[LIMIT] ... 100% ... Waiting for user choice   task is paused. Do not issue actions
+                                               until next trigger. See ## Errors above.
+
+ModuleNotFoundError in run_python output       the script needs a dependency. Install
+                                               via run_shell "pip install <pkg>" or
+                                               declare in action requirements.
+
+PermissionError / OSError on file write        the path is wrong, locked, or outside
+                                               the allowed scope. Verify with
+                                               list_folder; prefer workspace/ for
+                                               outputs.
+
+Long gaps between INFO lines (no activity)     the loop may be waiting for a trigger
+                                               (waiting_for_user_reply, scheduled
+                                               fire). Check the next trigger fire_at
+                                               in ProactiveManager / Scheduler.
+```
+
+**When logs are the only honest source of truth.** Some failures do not surface as `status=error` in the action result — they manifest as the action *seeming to work* but the side effect not happening (e.g., `run_shell` returns 0 but a script printed "ok" while silently catching an exception; an MCP tool returns success but logged a warning that the operation was a no-op). When you suspect a silent failure, grep the logs for the timestamp of your action and look for `WARNING` or unexpected `ERROR` lines around it.
+
+**Rotation and freshness.** Log files rotate at 50 MB and old files are kept for 14 days. The latest file by mtime is the one with current activity. If your investigation needs older history (e.g., a crash from yesterday), `list_folder logs/` and pick by timestamp.
+
+**Do not ask the user for log content you can read yourself.** The user does not have a better view than you do. If they ask "what's the error?", read the log, summarize, and explain. They are not your support layer — you are theirs.
+
+### Surfacing failures to the user
+
+Mid-task (recoverable):
+- `send_message` with: what failed (one sentence), what you tried (1-3 bullets), what you'll try next (one sentence).
+- Do not surface every transient retry. The user does not need to know about a single rate-limit retry that succeeded.
+
+Terminal (cannot recover):
+- For complex tasks: `send_message` with the failure summary + any salvageable partial result, then `task_end` with a failed-status summary.
+- For simple tasks: `send_message` with the failure, then `task_end`.
+- Mark task aborted via `task_manager.mark_task_cancel(...)` semantics ONLY through the proper action paths (don't try to invoke internals directly).
+- Never fabricate success. If you couldn't read the file, do not paraphrase what you "would have" found.
+
+### When you're blocked but not failed
+
+You're blocked when you don't know what to do next AND retrying won't help. The recovery is information, not action.
+
+```
+1. State the blocker plainly: "I can't proceed because <X>."
+2. List what you tried: "- Tried <A>: <result>. - Tried <B>: <result>."
+3. Ask ONE specific question — not "what should I do".
+   Good:  "Should I use the Slack bot token from settings.oauth.slack, or do you want me to reuse the existing /slack login session?"
+   Bad:   "What do you want me to do?"
+```
+
+### Common error-handling anti-patterns
+
+- **Treating action output as success without checking `status`.** The #1 source of silent failures. Always read the `status` field before using output.
+- **Retrying the same action with the same params** after `status=error` and no change. The error will repeat. Either change a parameter, change the action, or stop.
+- **Ignoring `"warning"` events** about action/token limits. The harness will pause your task soon — get ahead of it. At 80%, wrap up or send the partial result.
+- **Continuing to issue actions while limit-paused (100%).** They will not fire. The user is being shown a Continue/Abort dialog. Wait for the next trigger.
+- **Trying to retry after `LLMConsecutiveFailureError`.** The task is already cancelled by `_handle_react_error`. Do NOT recreate it. Tell the user the LLM configuration needs attention.
+- **Catching exceptions in `run_python` / `run_shell` and printing "ok".** The harness sees `status=success` if your script swallows the error. Always propagate non-zero exit codes / raise on failure.
+- **Fabricating success messages on failure.** Forbidden. If you couldn't read the file or call the API, do not paraphrase what you "would have" produced.
+- **Asking open-ended "what should I do" questions.** Always one specific question with an implied default ("Use the bot token from settings.oauth.slack, or reuse the existing /slack login session?").
+- **Self-detected logical loops.** The consecutive-failure breaker only catches LLM-call failures. If you keep choosing slightly different params for the same action and getting the same business-logic error (e.g., "user not found" three times with three different IDs you guessed), that is a logical loop. Stop and ask the user.
+
+### What the harness does NOT do for you
+
+- It does NOT change your approach when an action fails. You must.
+- It does NOT pick a different action when one returns `status=error`. You must.
+- It does NOT detect a logical loop you've created (same action with slightly different params, same error). The consecutive-failure breaker only catches LLM-call failures, not action-result failures. You must detect logical loops.
+- It does NOT verify that an action's `status=success` result actually achieved your goal. Verify (re-read the file you wrote, re-query the data you updated). See `## Tasks` Verify phase.
+
+---
+
+## Files
+
+### read_file
+- Returns `cat -n` formatted lines plus a `has_more` flag.
+- Default limit is 2000 lines. Use `offset` and `limit` for targeted reads.
+- For files larger than 500 lines: read the head first to learn structure, then `grep_files` for the section you need, then `read_file` with the right offset and limit.
+- Full input schema: [app/data/action/read_file.py](app/data/action/read_file.py).
+
+### grep_files
+Three output modes:
+- `files_with_matches`: returns file paths only. Use for discovery ("which files contain X").
+- `content`: returns matching lines with line numbers. Use for investigation.
+- `count`: returns match counts per file. Use for frequency checks.
+
+Supported parameters: `glob`, `file_type`, `before_context` / `after_context`, `case_insensitive`, `multiline`.
+
+Full input schema: [app/data/action/grep_files.py](app/data/action/grep_files.py).
+
+### stream_read + stream_edit
+- Use as a pair when modifying an existing file.
+- `stream_read` returns the exact bytes.
+- `stream_edit` applies a precise diff.
+- Preferred over `write_file` for edits. Preserves unrelated content and avoids whole-file overwrites.
+
+### write_file
+Use only when:
+- Creating a brand new file, OR
+- Doing a deliberate full rewrite of a small file.
+
+Never use `write_file` to patch an existing large file. Use `stream_edit`.
+
+### find_files vs list_folder
+- `list_folder`: top-level listing of a single directory.
+- `find_files`: recursive name pattern search across a tree.
+
+### convert_to_markdown vs read_pdf
+- `read_pdf`: direct PDF reading with page support.
+- `convert_to_markdown`: for office formats (docx, xlsx, pptx) you intend to grep afterwards.
+
+### Anti-patterns
+- Repeated full reads of large files. Use `grep_files` plus offset reads instead.
+- Chaining four `read_file` calls when one `grep_files` would answer the question.
+- Reading binary files as text. Use the dedicated action (`read_pdf`, `describe_image`, `understand_video`, etc.).
+
+---
+
+## File System
+
+Your persistent file system is `agent_file_system/`. Every file has a defined writer, reader, format, and update rule. Files marked `DO NOT EDIT` are managed by harness subsystems. Touching them creates inconsistency you cannot recover from.
+
+```
+agent_file_system/
+├── AGENT.md                  Operational manual (this file)
+├── USER.md                   User profile
+├── SOUL.md                   Personality (injected to system prompt)
+├── FORMAT.md                 Document / design standards
+├── MEMORY.md                 Distilled facts                     DO NOT EDIT
+├── EVENT.md                  Full event log                      DO NOT EDIT
+├── EVENT_UNPROCESSED.md      Memory-pipeline staging buffer      DO NOT EDIT
+├── CONVERSATION_HISTORY.md   Rolling dialogue log                DO NOT EDIT
+├── TASK_HISTORY.md           Task summaries                      DO NOT EDIT
+├── PROACTIVE.md              Recurring tasks + Goals/Plan/Status
+├── GLOBAL_LIVING_UI.md       Global Living UI design rules
+├── MISSION_INDEX_TEMPLATE.md Template for mission INDEX.md files
+└── workspace/                Sandbox for task outputs (see ## Workspace)
+```
+
+### Indexed for memory_search
+
+The MemoryManager indexes a fixed set of files for semantic retrieval ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py), constant `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Editing any of these triggers re-indexing via [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py). Other files in `agent_file_system/` are NOT indexed. To find content in non-indexed files, use `grep_files` directly.
+
+### AGENT.md
+- Purpose: operational manual for you.
+- Write access: user (manually); you (only for operational improvements you have learned, see `## Self-Edit`).
+- Read pattern: `read_file` / `grep_files` on demand. Always grep by `## <Topic>` header.
+- Format: structured markdown. Stable `## <Topic>` headers. HTML comment markers (`<!-- name -->` ... `<!-- /name -->`) around schema and command blocks.
+- Update rule: bump `version:` in front matter on material changes. Sync to `app/data/agent_file_system_template/AGENT.md` when the change should ship to new installs.
+
+### USER.md
+- Purpose: persona and preferences of the user. Read at the start of any user-facing task.
+- Write access: the agent (after confirming with the user); the onboarding wizard.
+- Read pattern: at session start, when personalizing responses, when picking communication channel.
+- Format: plain markdown sections. Standard sections: `## Identity`, `## Communication Preferences`, `## Agent Interaction`, `## Life Goals`, `## Personality`.
+- Update rule: confirm the preference is durable before writing. One-off requests do not belong here.
+
+### SOUL.md
+- Purpose: personality, tone, behavior. Injected directly into the system prompt every turn.
+- Write access: user (primarily); you only on explicit user request.
+- Read pattern: the system reads on every turn. You do NOT need to `read_file` it during normal operation.
+- Caution: edits affect every interaction immediately on next turn. Confirm with user before saving.
+
+### FORMAT.md
+- Purpose: design and formatting standards for documents you generate.
+- Write access: user (preferences); you when the user supplies a new rule (with confirmation).
+- Read pattern: `grep_files "## <filetype>" agent_file_system/FORMAT.md` before generating any document. See `## Documents`.
+- Sections: `## global` (universal rules), `## pptx`, `## docx`, `## xlsx`, `## pdf`. Type-specific sections override `## global`.
+
+### MEMORY.md
+- Purpose: distilled long-term memory. Survives across sessions.
+- Write access: ONLY the memory processor (daily 3am job, plus startup replay if EVENT_UNPROCESSED.md is non-empty).
+- Hard rule: you MUST NOT edit MEMORY.md directly. Use the memory pipeline. See `## Memory`.
+- Read pattern: `memory_search` action (RAG, returns relevance-ranked pointers). Do NOT grep MEMORY.md directly for retrieval.
+- Format: `[YYYY-MM-DD HH:MM:SS] [type] content` — one fact per line.
+- Types: `capability`, `project`, `workspace`, `focus`, `preference`, `analysis`, `user_complaint`, `system_warning`, `system_limit`.
+
+### EVENT.md
+- Purpose: complete chronological event log. Append-only.
+- Write access: EventStreamManager. Hard rule: DO NOT edit.
+- Read pattern: `read_file` / `grep_files` for self-troubleshooting. See `## Errors` for log workflow.
+- Format: `[YYYY/MM/DD HH:MM:SS] [event_type]: payload`. Multi-line payloads continue on subsequent lines.
+- Auto-rotated when size threshold is exceeded.
+
+### EVENT_UNPROCESSED.md
+- Purpose: staging buffer for events awaiting memory distillation.
+- Write access: EventStreamManager (filtered subset of EVENT.md events). Hard rule: DO NOT edit.
+- Read pattern: the memory processor reads it daily 3am. See `## Memory`.
+- Cleared: after each successful memory-processing run.
+- Filter: events of kind `action_start`, `action_end`, `todos`, `error`, `waiting_for_user` are NOT staged. The pipeline focuses on user-facing dialogue and important state changes.
+- Skip flag: during memory-processing tasks, `set_skip_unprocessed_logging(True)` prevents the task's own events from looping back. Reset automatically on `task_end`.
+
+### CONVERSATION_HISTORY.md
+- Purpose: rolling dialogue record across all sessions.
+- Write access: EventStreamManager (on every user/agent message). Hard rule: DO NOT edit.
+- Read pattern: when restoring context for a returning user or reviewing what was said.
+- Format: `[YYYY/MM/DD HH:MM:SS] [sender]: message`. Sender is `user` or `agent`. Multi-line messages continue under one header.
+- Lifespan: permanent. Never auto-cleared.
+
+### TASK_HISTORY.md
+- Purpose: summary of every completed (or cancelled) task.
+- Write access: appended on `task_end`. Hard rule: DO NOT edit.
+- Read pattern: when checking past outcomes for a similar task.
+- Format: one markdown section per task:
+  ```
+  ### Task: <task name>
+  - **Task ID:** <id>
+  - **Status:** completed | cancelled | failed
+  - **Created:** <ISO timestamp>
+  - **Ended:** <ISO timestamp>
+  - **Summary:** <one-paragraph outcome>
+  - **Instruction:** <original task instruction>
+  - **Skills:** <skill names used>
+  - **Action Sets:** <action set names used>
+  ```
+
+### PROACTIVE.md
+- Purpose: recurring proactive task definitions plus the planner-maintained Goals / Plan / Status section.
+- Write access: `recurring_add` / `recurring_update_task` / `recurring_remove` actions; planners (day, week, month).
+- Read pattern: every heartbeat (every 30 min); planners on their schedules; you when the user asks about scheduled work. See `## Proactive`.
+- Format: YAML blocks between `<!-- PROACTIVE_TASKS_START -->` and `<!-- PROACTIVE_TASKS_END -->` markers, followed by a Goals / Plan / Status section.
+- Authority: PROACTIVE.md is the source of truth for the Decision Rubric, Permission Tiers, and recurring-task YAML schema. Do NOT duplicate that content elsewhere.
+
+### GLOBAL_LIVING_UI.md
+- Purpose: global design rules applied to every Living UI project.
+- Write access: user (primarily). You only when the user supplies a new universal rule with confirmation.
+- Read pattern: before creating any Living UI project. See `## Living UI`.
+- Sections: Design Preferences (colors, theme, font, border radius, spacing), Always Enforced rules, Optional rules, Custom rules.
+
+### MISSION_INDEX_TEMPLATE.md
+- Purpose: template for `workspace/missions/<name>/INDEX.md`. See `## Workspace`.
+- Write access: static template. DO NOT edit.
+- Read pattern: when starting a mission, copy this template into the mission directory and fill it in.
+- Fields: Goal, Status, Key Findings, What's Been Tried, Next Steps, Resources & References, Constraints & Notes.
+
+### Living UI projects (workspace/living_ui/)
+
+Living UI projects live at `agent_file_system/workspace/living_ui/<project_name>_<hash>/`. Internal structure varies project to project depending on what the user asked for (different stacks, frameworks, file layouts). Do NOT assume any particular structure beyond the three required files below. To see what's actually in a specific project, `list_folder` it. For lifecycle (create, modify, restart, inspect), use `living_ui_actions`. See `## Living UI`.
+
+Required files (every project has these):
+
+```
+workspace/living_ui/<name>_<hash>/
+├── LIVING_UI.md          Per-project doc: purpose, decisions, project-specific rules
+├── config/
+│   └── manifest.json     Project metadata: name, hash, ports, capabilities
+└── logs/                 Project logs (timestamped). Format and filenames vary per project.
+```
+
+- `LIVING_UI.md`: read this first when working on an existing project. Records purpose, design decisions, and any project-specific overrides of `GLOBAL_LIVING_UI.md`.
+- `config/manifest.json`: read by the runtime to identify the project and its assigned ports. Do not rename a project directory by hand. Re-register via `living_ui_actions` instead.
+- `logs/`: where the project's runtime, build, and console output land. First place to grep when a project misbehaves.
+
+Everything else (backend, frontend, build output, dependency caches, databases) is project-specific. To learn what a fresh-from-template project would contain (one possible shape, not the only one), see [app/data/living_ui_template/](app/data/living_ui_template/).
+
+### Files outside agent_file_system/
+
+Some persistent state the agent interacts with lives outside this directory:
+
+```
+app/config/settings.json              model, API keys, OAuth, cache              (## Configs)
+app/config/mcp_config.json            MCP server registry                         (## MCP)
+app/config/skills_config.json         enabled / disabled skills                   (## Skills)
+app/config/external_comms_config.json platform listener configs                   (## Integrations)
+app/config/scheduler_config.json      cron schedules                              (## Proactive)
+app/config/onboarding_config.json     first-run state                             (## Onboarding)
+skills/<name>/SKILL.md                installed skills                            (## Skills)
+.credentials/<platform>.json          OAuth tokens, bot tokens, API keys
+                                      DO NOT print contents to chat or logs
+logs/<timestamp>.log                  runtime logs                                (## Errors)
+chroma_db_memory/                     ChromaDB index for memory_search
+                                      DO NOT edit
+```
+
+---
 
-### 5. Memory - Learn and Remember
-When you learn something useful (user preferences, project context, solutions to problems):
-- Use `memory_search` action to check if relevant memory already exists
-- Store important learnings in MEMORY.md via memory processing actions
-- Use `read_file` to read USER.md and AGENT.md to understand context before tasks
-- Use `stream_edit` to update USER.md with user preferences you discover
-- Use `stream_edit` to update AGENT.md with operational improvements
+## Workspace
+
+`agent_file_system/workspace/` is your sandbox for task output. Three subdirectories with distinct lifecycles:
+
+```
+agent_file_system/workspace/
+├── <files at root>           Persistent task outputs the user should keep across sessions
+├── tmp/
+│   └── {task_id}/            Per-task scratch directory. Auto-cleaned.
+├── missions/
+│   └── <mission_name>/       Multi-task initiative. Persists indefinitely.
+│       ├── INDEX.md          Required (template at MISSION_INDEX_TEMPLATE.md)
+│       └── <mission files>
+└── living_ui/
+    └── <name>_<hash>/        Living UI projects. See ## File System.
+```
+
+### Where to put a file
+
+```
+Type of file                                      → Destination
+final document the user should keep               → workspace/<filename>
+draft, sketch, intermediate state, scratch        → workspace/tmp/{task_id}/<filename>
+mission deliverable (multi-task initiative)       → workspace/missions/<mission_name>/<filename>
+Living UI project file                            → workspace/living_ui/<name>_<hash>/...
+```
 
-## Proactive Behavior
+### Lifecycle rules
 
-You activate on schedules (hourly/daily/weekly/monthly).
+- `workspace/` (root): never auto-cleaned. Anything you save here persists until the user deletes it.
+- `workspace/tmp/{task_id}/`: created automatically by `task_manager._prepare_task_temp_dir(task_id)` when a task starts. Cleaned by `task_manager.cleanup_all_temp_dirs(...)` on `task_end` AND on agent startup (excluding currently-restored tasks). Use this for anything you don't need after the task ends.
+- `workspace/missions/<name>/`: never auto-cleaned. The mission's `INDEX.md` is what future-you reads to restore context.
+- `workspace/living_ui/<name>_<hash>/`: managed via `living_ui_actions`. Do not rename or delete by hand. See `## Living UI`.
 
-Read PROACTIVE.md for more instruction.
+### Path discipline
+
+- Always use absolute paths when invoking actions: `agent_file_system/workspace/<...>`. Never relative paths.
+- Inside an action result you may receive a path; pass it through verbatim. Do not normalize.
+- Filenames: lowercase, snake_case or kebab-case, no spaces. Example: `tsla_analysis_2026_05_04.pdf`.
+- For task-scoped files use the actual `task_id`, not a guess. The harness sets `task.temp_dir` on task creation; the path is `agent_file_system/workspace/tmp/{task_id}/`.
+
+### Missions: when to create one
+
+Create `workspace/missions/<mission_name>/INDEX.md` when ANY of:
+- Work spans multiple sessions or days.
+- Plan has more than ~10 todos.
+- User uses words like "project", "initiative", "ongoing", "campaign", "phase".
+- Output of this task will feed into a future task.
+
+If the answer is "no" to all, do NOT create a mission. A single complex task is enough.
+
+### Missions: scan-on-start
+
+At the start of every complex task:
+```
+1. list_folder agent_file_system/workspace/missions/
+2. If any directory name looks relevant to the user's request:
+     read_file agent_file_system/workspace/missions/<name>/INDEX.md
+3. Decide:
+     - Resume an existing mission              → continue updating its INDEX.md
+     - Create a new mission                    → copy MISSION_INDEX_TEMPLATE.md
+     - One-off complex task, not a mission     → no mission directory
+```
+
+This is non-optional. Skipping the scan causes duplicate work and lost context.
+
+### Mission INDEX.md fields
+
+Template lives at [agent_file_system/MISSION_INDEX_TEMPLATE.md](agent_file_system/MISSION_INDEX_TEMPLATE.md). Required fields:
+
+- **Goal**: what "done" looks like, with concrete deliverables.
+- **Status**: one of `Not started | In progress | Blocked | Completed | Abandoned`. Plus last task summary, last updated date.
+- **Key Findings**: distilled discoveries. The most important section. This is what future-you reads to restore context. Keep it tight and current.
+- **What's Been Tried**: approaches plus outcomes. Prevents repeating failed attempts.
+- **Next Steps**: concrete actions a fresh task can pick up immediately. Be specific enough that no further investigation is needed to start.
+- **Resources & References**: links, file paths, tools, contacts.
+- **Constraints & Notes**: deadlines, user preferences, environmental limits.
+
+### Mission INDEX.md update cadence
+
+- At task start (resuming a mission): read INDEX.md fully. Add a `Status` line for the new task.
+- During the task: append to `Key Findings` whenever you learn something durable. Append to `What's Been Tried` after any completed approach (success or failure).
+- Before `task_end`: update `Status`, write `Next Steps` so a fresh task session can pick up immediately. If the mission is done, mark `Status: Completed`.
+
+A mission with stale `Next Steps` is worse than no mission. Always leave it actionable.
+
+### What does NOT belong in workspace/
+
+- Configuration files (use `app/config/`).
+- Skills (use `skills/`).
+- Credentials (use `.credentials/`).
+- Logs (auto-go to `logs/<timestamp>.log`).
+- Editing AGENT.md / USER.md / SOUL.md / FORMAT.md (these are in `agent_file_system/`, not `workspace/`).
+
+---
+
+## Documents
+
+[agent_file_system/FORMAT.md](agent_file_system/FORMAT.md) is the source of truth for every document you generate (PDF, pptx, docx, xlsx, and any other file-format output). Read it before generating; it carries the user's brand colors, fonts, writing style, and layout rules.
+
+### FORMAT.md structure
+
+```
+## global       universal rules: brand colors, fonts, writing style, layout
+## pptx         slide-deck specifics (aspect ratio, margins, slide types, typography)
+## docx         Word document standards
+## xlsx         spreadsheet standards
+## pdf          PDF generation standards
+```
+
+The user can add more file-type sections (e.g., `## md`, `## csv`). Type-specific sections OVERRIDE `## global` for that file type.
+
+### Protocol before generating any document
+
+```
+1. grep_files "## <filetype>" agent_file_system/FORMAT.md -A 50
+   Read the file-type section in full.
+
+2. grep_files "## global" agent_file_system/FORMAT.md -A 50
+   Read the global section in full.
+
+3. If the file-type section is missing, fall back to global only.
+
+4. Apply the combined rules to your output: colors, fonts, spacing,
+   layout, writing style, language conventions, brand assets.
+
+5. After generating, verify the output matches by re-reading the produced
+   file (or summary of it). Especially for visual artifacts (PDF, pptx).
+```
+
+This is non-optional. Generating documents without reading FORMAT.md produces inconsistent outputs the user has to redo.
+
+### Action support
+
+Document generation actions in the standard action set:
+```
+create_pdf              build a PDF from markdown / text
+                        (preferred over rendering via run_python)
+convert_to_markdown     normalize office formats before further processing
+read_pdf                read a PDF with page support
+```
+
+Skills that compose document workflows (sample):
+```
+pdf, docx, pptx, xlsx          per-format end-to-end generation skills
+file-format                    format normalization and conversion
+compile-report-advance         multi-source compilation
+```
+
+If a skill exists for the target format (e.g., `pdf`), prefer invoking it (`/pdf` slash or LLM-selected) over composing actions yourself. Skills already encode the FORMAT.md read step and the right action sequence.
+
+### Updating FORMAT.md
+
+Edit when the user gives a durable formatting preference:
+```
+"always use a serif font in reports"            → ## global, font rule
+"company logo is at /path/to/logo.png"          → ## global, brand asset
+"PDF reports should have 1-inch margins"        → ## pdf, margins
+"slide decks should be 16:9 with dark theme"   → ## pptx, layout / theme
+```
+
+Edit procedure:
+```
+1. Confirm scope: "global rule for all docs, or just for <filetype>?"
+2. stream_edit FORMAT.md, write to the right section.
+3. Send the user the exact lines you wrote so they can correct.
+```
+
+DO NOT silently change FORMAT.md. The user owns their style guide.
+
+### Pitfalls
+
+- Generating a document without reading FORMAT.md. Visible inconsistency cost.
+- Mixing global and per-type rules incorrectly: per-type wins for that type, global wins everywhere else.
+- Adding a new file-type section without user consent. Ask first.
+- Storing the user's brand assets (logo URLs, colors) in MEMORY.md or USER.md instead of FORMAT.md. They belong in FORMAT.md.
+
+---
+
+## Living UI
+
+"Living UI" = generated React / HTML / single-page-app projects that have persistent state and are served from CraftBot. Each project is a self-contained mini-app (kanban board, habit tracker, dashboard, etc.) the user can interact with through their browser. Lifecycle is managed via `living_ui_actions`.
+
+Code: [app/data/action/living_ui_actions.py](app/data/action/living_ui_actions.py). File system layout: see `## File System` "Living UI projects" subsection.
+
+### What you actually do for a Living UI request
+
+You do NOT hand-write the project scaffold. The Living UI generator handles file scaffolding via the `living_ui_actions` action set. Your job is:
+1. Capture the user's intent (what is the app for, what state does it persist, what views / interactions).
+2. Apply GLOBAL_LIVING_UI.md design rules and any project-specific overrides.
+3. Use the appropriate Living UI skill (`living-ui-creator`, `living-ui-modify`, `living-ui-manager`) to drive the generator.
+
+### Skills for Living UI lifecycle
+
+```
+living-ui-creator    start a new project. Walks scaffolding + initial state design.
+living-ui-modify     edit an existing project (add features, change layout, fix bugs).
+living-ui-manager    list, inspect, archive, restart projects.
+```
+
+Prefer invoking these via slash (`/living-ui-creator`) or via LLM selection. They encode the right read-rules-first protocol and the right action sequence.
+
+### Protocol BEFORE creating any Living UI project
+
+```
+1. Read GLOBAL_LIVING_UI.md (small file, ~80 lines). It defines:
+   - Primary / secondary / accent colors
+   - Theme behavior (system / dark / light)
+   - Component preferences (preset components, no inline styles,
+     react-toastify, async spinners, toast CRUD feedback,
+     confirmation dialogs, validation, mobile responsive, etc.)
+   - Optional rules (drag-and-drop, keyboard shortcuts, item count
+     badges, search/filter, bulk selection, dark-mode-only, animations)
+   - User-defined custom rules
+
+2. Apply global rules first; only override on explicit user instruction.
+
+3. After creation, the project should respect EVERY "Always Enforced" rule
+   in GLOBAL_LIVING_UI.md (no inline styles, preset components, async
+   spinners, etc.).
+```
+
+If the user wants project-specific design that conflicts with GLOBAL_LIVING_UI.md, confirm the override before applying.
+
+### Per-project structure (what's guaranteed)
+
+Each project lives at `agent_file_system/workspace/living_ui/<name>_<hash>/`. The internal structure varies per project (different stacks possible). Only three files are guaranteed:
+
+```
+LIVING_UI.md          per-project doc: purpose, decisions, project-specific rules
+config/manifest.json  project metadata: name, hash, ports, capabilities
+logs/                 project runtime / build / console logs (timestamped)
+```
+
+For full file-system details and the do-not-rename rule, see `## File System` "Living UI projects" subsection.
+
+### Editing an existing project
+
+```
+1. read LIVING_UI.md to understand purpose + project-specific rules.
+2. list_folder the project to see what's actually there.
+3. Use living-ui-modify skill (don't hand-edit unless the skill
+   isn't suitable).
+4. After changes, the project should still respect GLOBAL_LIVING_UI.md.
+```
+
+When the project misbehaves: grep `logs/` first (frontend console output is piped there via ConsoleCapture). See `## File System` "Living UI projects" subsection for log details.
+
+### Updating GLOBAL_LIVING_UI.md
+
+Edit only when the user gives a NEW universal rule that should apply to ALL Living UI projects (e.g., "never use animations", "always include dark mode toggle"). For project-specific overrides, edit the project's own `LIVING_UI.md` instead.
+
+Edit procedure: same pattern as FORMAT.md — confirm scope, stream_edit, confirm to user.
+
+### Pitfalls
+
+- Hand-writing the project scaffold instead of using `living_ui_actions` / Living UI skills. The generator does it correctly; manual scaffolds drift from the template.
+- Using inline styles. Forbidden by GLOBAL_LIVING_UI.md.
+- Skipping the GLOBAL_LIVING_UI.md read for "simple" projects. Even simple ones should respect global rules.
+- Renaming a project directory by hand. Re-register via `living_ui_actions` instead — the manifest.json is the source of truth for the project's name.
+- Putting project-wide design changes in GLOBAL_LIVING_UI.md when they should be in the per-project LIVING_UI.md.
+
+---
+
+## Actions
+
+Actions are the only way you do anything. The runtime presents the currently-available actions to you in your prompt each turn. If you need a capability that is not in the current list, you must either expand the active action sets (see `## Action Sets`) or read the source to learn what to call.
+
+### Where actions live
+
+Built-in actions are Python files under [app/data/action/](app/data/action/). The action name does NOT always match the filename:
+
+```
+app/data/action/<file>.py             one or more @action() registrations
+app/data/action/CUSTOM_ACTION_GUIDE.md guide for authoring new actions
+app/data/action/<platform>/...        platform-specific bundles (one file may register 10+ actions)
+```
+
+Examples of files with multiple registrations:
+- `action_set_management.py` registers `add_action_sets`, `remove_action_sets`, `list_action_sets`.
+- `skill_management.py` registers `list_skills`, `use_skill`.
+- `integration_management.py` registers `list_available_integrations`, `connect_integration`, `check_integration_status`, `disconnect_integration`.
+- `discord/discord_actions.py`, `slack/slack_actions.py`, `telegram/telegram_actions.py`, `notion/notion_actions.py`, `linkedin/linkedin_actions.py`, `jira/jira_actions.py`, `github/github_actions.py`, `outlook/outlook_actions.py`, `whatsapp/whatsapp_actions.py`, `twitter/twitter_actions.py`, `google_workspace/{gmail,google_calendar,google_drive}_actions.py` each register many actions.
+
+Total registered built-in actions: roughly 195 (varies by version). The exact number is logged at startup in `logs/<timestamp>.log` — search for `Action registry loaded`.
+
+### How to discover actions
+
+You have three discovery paths. Pick by purpose.
+
+**1. By name (when you already know it).** Read the source:
+```
+read_file app/data/action/<action_name>.py
+```
+
+**2. By capability (when you do NOT know the name).** Grep descriptions and names across the folder:
+```
+grep_files 'name="' app/data/action/ -A 1            # list all action names + first description line
+grep_files 'description=' app/data/action/ -A 0      # list all descriptions
+grep_files '<keyword>' app/data/action/ -A 2 -B 1    # find actions matching a concept
+```
+
+**3. By currently-loaded set (what you can call right now).** Two options:
+- The runtime puts the current action list in your prompt every turn. That list is authoritative.
+- Call the `list_action_sets` action to see which sets are loaded plus all actions in them. Useful when the prompt list is truncated or you suspect a set is missing.
+
+### `@action(...)` decorator schema
+
+Every action is registered via the `@action` decorator at [agent_core/core/action_framework/registry.py](agent_core/core/action_framework/registry.py). When you read an action's `.py` file, these are the fields you will see:
+
+```
+name             str   required. Unique identifier the LLM uses to call the action.
+description      str   shown to the LLM. This is how you decide whether to use the action.
+mode             str   "CLI" | "ALL". Visibility filter.
+default          bool  legacy. If True, action is always available. Prefer action_sets.
+execution_mode   str   "internal" (in-process) | "sandboxed" (ephemeral venv subprocess).
+platforms        str|list  "linux" | "windows" | "darwin" | "all". Default: ["all"].
+input_schema     dict  JSON-schema-like description of parameters. Read this for param names and types.
+output_schema    dict  JSON-schema-like description of return shape. Read this to know what to expect.
+requirement      list  pip packages auto-installed in sandbox before execution.
+test_payload     dict  test input for diagnostic harness. The "simulated_mode" key bypasses real execution.
+action_sets      list  set names this action belongs to. Determines when it's loaded.
+parallelizable   bool  default True. False = action runs alone in its turn (write ops, state changes).
+```
+
+Key implications when reading an action:
+- `mode="CLI"` actions exist (e.g. `read_file`, `task_start`). They are loaded by default.
+- `parallelizable=False` actions cannot be batched. The router will sequence them. Examples: `task_update_todos`, `add_action_sets`, `remove_action_sets`.
+- `execution_mode="sandboxed"` means the action runs in a fresh venv subprocess with `requirement` packages installed automatically. `run_python` is sandboxed; most other actions are internal.
+- `default=True` means the action is in the action list regardless of which sets are loaded. Common defaults: `task_start`, `send_message`, `ignore`. Prefer adding to an `action_sets` list over using `default=True`.
+
+### Built-in action categories (orientation only — read source for current state)
+
+```
+core                     send_message, task_start, task_end, task_update_todos, ignore, wait,
+                         add_action_sets, remove_action_sets, list_action_sets,
+                         list_skills, use_skill,
+                         list_available_integrations, connect_integration,
+                         check_integration_status, disconnect_integration
+
+file_operations          read_file, grep_files, find_files, list_folder, stream_edit, write_file,
+                         read_pdf, convert_to_markdown, create_pdf
+
+shell                    run_shell, run_python
+
+web_research             web_fetch, web_search, http_request
+
+memory                   memory_search
+
+proactive / scheduler    schedule_task, scheduled_task_list, schedule_task_toggle,
+                         remove_scheduled_task, recurring_add, recurring_read,
+                         recurring_update_task, recurring_remove
+
+image                    describe_image, generate_image, perform_ocr
+
+video                    understand_video
+
+clipboard                clipboard_read, clipboard_write
+
+comms                    send_message_with_attachment
+
+living_ui                living_ui_http, living_ui_import_external, living_ui_import_zip,
+                         living_ui_notify_ready, living_ui_report_progress, living_ui_restart
+
+per-platform integrations  Discord, Slack, Telegram, Notion, LinkedIn, Jira, GitHub,
+                           Outlook, WhatsApp, Twitter, Google Workspace
+                           (each has its own bundle file; loaded via integration action sets)
+```
+
+This grouping is informal. The authoritative grouping per action is the `action_sets=[...]` list in its decorator. When in doubt, grep the source.
+
+### Calling an action
+
+You do not call actions directly in code. You emit an action decision in your turn output. Format (illustrative):
+
+```
+{"action_name": "read_file", "parameters": {"file_path": "agent_file_system/AGENT.md", "limit": 200}}
+```
+
+The router validates the name and parameters against the action's `input_schema`, then the executor runs it. The result returns as a dict matching `output_schema`. See `## Errors` for the standard `{"status": "success" | "error", ...}` envelope.
+
+### Authoring a new action
+
+If you discover the harness is missing a capability you need repeatedly:
+1. Read [app/data/action/CUSTOM_ACTION_GUIDE.md](app/data/action/CUSTOM_ACTION_GUIDE.md).
+2. Pick a similar existing action as a template (e.g. for a file op, copy `read_file.py`).
+3. Create the new file under [app/data/action/](app/data/action/) with a single `@action(...)` decorator.
+4. Register it in the right `action_sets`.
+5. Restart is required for code changes (hot-reload covers configs, NOT new action files). See `## Hot Reload`.
+
+For everything routine (existing capabilities), prefer composing existing actions over authoring new ones.
+
+---
+
+## Action Sets
+
+An action set is a named bundle of actions you load together. Loading a set makes all its actions available in your prompt; the LLM can then call them. Sets exist to keep your prompt small (only the actions you need) without sacrificing capability.
+
+Code: [app/action/action_set.py](app/action/action_set.py) (`ActionSetManager`). Set descriptions: [app/action/action_set.py](app/action/action_set.py) `DEFAULT_SET_DESCRIPTIONS`.
+
+### How sets are discovered
+
+Sets are NOT hardcoded. They are discovered dynamically by scanning every registered action's `action_sets=[...]` declaration. Any name an action declares becomes a valid set. This means:
+- Adding a new action to a new set name silently creates that set.
+- MCP servers auto-register as `mcp_<server_name>` sets via `action_set_name` in `mcp_config.json`. See `## MCP`.
+- A set with no actions is invisible (the discovery scans actions, not a static list).
+
+To list every set currently visible to the runtime, call the `list_action_sets` action.
+
+### Built-in sets (with curated descriptions)
+
+`DEFAULT_SET_DESCRIPTIONS` has explicit descriptions for these eight sets:
+
+```
+core                  Essential actions, always available
+file_operations       File and folder manipulation
+web_research          Internet search and browsing
+document_processing   PDF and document handling
+image                 Image viewing, analysis, OCR
+video                 Video analysis
+clipboard             Clipboard read/write
+shell                 Command line and Python execution
+```
+
+Any set name not in `DEFAULT_SET_DESCRIPTIONS` is presented to the LLM as `Custom action set: <name>`.
+
+### Other sets actually used by built-in actions
+
+Beyond the eight curated sets, these sets exist because actions declare them:
+
+```
+proactive             schedule_task, scheduled_task_list, recurring_*, schedule_task_toggle, ...
+scheduler             schedule_task, schedule_task_toggle (alongside proactive)
+content_creation      generate_image, create_pdf, ...
+living_ui             living_ui_http, living_ui_restart, ...
+
+per-integration sets (loaded only when the user has the integration connected):
+discord, slack, telegram_bot, telegram_user, whatsapp, twitter,
+notion, linkedin, jira, github, outlook, google_workspace
+```
+
+This list is illustrative, not authoritative. Run `list_action_sets` for the live list. Read [app/action/action_set.py](app/action/action_set.py) for the source.
+
+### `core` is always loaded
+
+[app/action/action_set.py](app/action/action_set.py) `compile_action_list`:
+
+```
+required_sets = set(selected_sets) | {"core"}
+```
+
+You cannot opt out of `core`. Whatever else you pass to `task_start`, `core` is added. `core` includes (at minimum):
+
+```
+send_message, task_start, task_end, task_update_todos, ignore, wait,
+add_action_sets, remove_action_sets, list_action_sets,
+list_skills, use_skill,
+list_available_integrations, connect_integration,
+check_integration_status, disconnect_integration,
+clipboard_read, clipboard_write
+```
+
+(Note: `clipboard_read` and `clipboard_write` are in `core`, not in a separate `clipboard` set, despite the curated description suggesting otherwise.)
+
+### How sets are loaded
+
+Three mechanisms, in order of preference:
+
+1. **At `task_start`** — pass the names in the `action_sets` parameter. The LLM-driven creator (`do_create_task`) auto-selects sets based on the task description; you can also pre-select via skill slash commands like `/pdf`. `core` is added automatically.
+2. **Mid-task** — call `add_action_sets(action_sets=[...])` or `remove_action_sets(action_sets=[...])`. The action list is recompiled and the new actions appear in the next turn's prompt.
+3. **Via skill selection** — if a skill's `SKILL.md` frontmatter has `action-sets: [...]`, those sets are auto-loaded when the skill is selected. See `## Skills`.
+
+After loading, the new actions ARE in your prompt the next turn. You do not need to re-fetch or refresh anything.
+
+### Picking the right sets
+
+Match the task's actual needs. Loading every set bloats the prompt and slows action selection.
+
+```
+Lightweight task                  core + file_operations
+Web research / lookup             core + web_research
+Document generation               core + file_operations + document_processing
+Multimedia work                   core + image (and/or video)
+Shell / scripting                 core + shell + file_operations
+Living UI work                    core + living_ui + file_operations + shell
+Proactive task setup              core + proactive
+Per-platform integration          core + <integration_name>  (e.g. core + slack)
+```
+
+Defaults that almost always make sense: `core + file_operations`. Add others as the task requires.
+
+### Tracking what is loaded
+
+Two ways to know what set is currently active for a task:
+1. The current prompt's action list (always authoritative).
+2. The `list_action_sets` action returns `{ available_sets, current_sets, current_actions }`.
+
+If you suspect a set was supposed to be loaded but isn't (an action you expect to see is missing), call `list_action_sets` to confirm before assuming you have to manually add it with `add_action_sets`.
+
+### Set lifecycle relative to a task
+
+- Sets are LOCKED when the task is created. The task's `compiled_actions` list is built once.
+- `add_action_sets` / `remove_action_sets` are the only mid-task mutations. They re-run `compile_action_list` and update the task's available actions.
+- When the task ends, the set selection is gone. The next task starts fresh.
+- Skills do NOT swap mid-task. To use a different skill, end the task and start a new one.
+
+See `## Tasks` for task-level lifecycle and `## Runtime` for how the action list reaches your prompt each turn.
+
+---
+
+## Slash Commands
+
+Slash commands are USER-invoked at the chat input. The agent does NOT call slash commands; the agent uses actions (see `## Actions`). Slash commands are documented here so you understand what the user just typed when they invoke one, and so you can answer questions about them.
+
+Sources of truth (in order of authority):
+1. Built-in command files: [app/ui_layer/commands/builtin/](app/ui_layer/commands/builtin/). One file per top-level command.
+2. Integration commands: dynamically registered from `INTEGRATION_HANDLERS` in [app/credentials/handlers.py](app/credentials/handlers.py). One slash command per registered handler.
+3. Skill commands: every skill with `user-invocable: true` (default) in its `SKILL.md` frontmatter is auto-registered as `/<skill_name>`.
+
+Run `/help` for the live list. If you need to verify a specific command, read its file.
+
+### General commands
+
+```
+/help [command]      list all commands, or detail one. Always available.
+/menu                show the main menu
+/clear               clear the conversation
+/clear_tasks         clear finished tasks (completed, failed, aborted) from the action panel
+/reset               reset the agent to its initial state
+/exit                quit the application
+/update              check for updates and update CraftBot
+/provider <name>     switch LLM provider (openai, anthropic, google, byteplus, remote)
+```
+
+### Credential and integration overview
+
+```
+/cred list           list all stored credentials across integrations
+/cred status         show connection status for every integration
+/cred integrations   list available integration types
+```
+
+`/cred` does not connect or disconnect; use `/<integration>` for that.
+
+### MCP server management
+
+```
+/mcp list                          list configured MCP servers + enabled state
+/mcp add <name> <command> [args]   register a new MCP server (stdio)
+/mcp add-json <json>               register from a full JSON entry
+/mcp remove <name>                 remove a server
+/mcp enable <name>                 enable a server (next reload picks it up)
+/mcp disable <name>                disable a server
+/mcp env <name> <KEY> <value>      set an env variable on a server entry
+```
+
+Edits go to [app/config/mcp_config.json](app/config/mcp_config.json) and are hot-reloaded. See `## MCP` and `## Configs`.
+
+### Skill management
+
+```
+/skill list                                    list installed skills + enabled state
+/skill info <name>                             show metadata + body of a skill
+/skill enable <name>                           move a skill into enabled_skills
+/skill disable <name>                          move a skill into disabled_skills
+/skill install <source>                        install from a git URL or path
+/skill create [name] [description]             scaffold a new skill (uses craftbot-skill-creator)
+/skill remove <name>                           delete a skill from skills/ directory
+/skill reload                                  rediscover skills (manual hot-reload)
+```
+
+Edits go to [app/config/skills_config.json](app/config/skills_config.json) and the [skills/](skills/) directory. See `## Skills`.
+
+### Skill direct invocation
+
+Every skill with `user-invocable: true` in its frontmatter (default) is registered as a slash command:
+
+```
+/<skill_name> [args]    invoke the skill directly
+```
+
+When the user types this, the runtime starts a task with the skill pre-selected (bypassing LLM skill selection in `do_create_task`). Examples that exist in the current build: `/pdf`, `/docx`, `/pptx`, `/xlsx`, `/weather-check`, `/get-weather`, etc. The list depends on which skills are enabled in [app/config/skills_config.json](app/config/skills_config.json).
+
+### Integration commands (auth + lifecycle)
+
+For each registered integration in `INTEGRATION_HANDLERS`, a slash command `/{integration}` is auto-registered:
+
+```
+/<integration> status                    show connection state, accounts
+/<integration> connect [...credentials]  connect (token-based) — fields depend on integration
+/<integration> disconnect [account_id]   remove a connection
+/<integration> login-qr                  for whatsapp_web (QR scan flow)
+/<integration> invite                    for OAuth-capable integrations (browser flow)
+```
+
+Currently registered (per [app/credentials/handlers.py](app/credentials/handlers.py) `INTEGRATION_HANDLERS`):
+
+```
+google              OAuth flow.   /google invite | status | disconnect
+slack               OAuth + token. /slack invite | connect <bot_token> [workspace_name] | status | disconnect
+notion              OAuth + token. /notion invite | connect <token> | status | disconnect
+linkedin            OAuth flow.   /linkedin invite | status | disconnect
+discord             Token flow.   /discord connect <bot_token> | status | disconnect
+telegram            Bot + user.   /telegram connect <bot_token> | status | disconnect
+                                  (user-account flow has additional sub-commands; see /help telegram)
+whatsapp            Web (QR).     /whatsapp login-qr [phone] | status | disconnect
+whatsapp_business   API tokens.   /whatsapp_business connect <phone_number_id> <access_token> | status | disconnect
+outlook             OAuth flow.   /outlook invite | status | disconnect
+jira                Token flow.   /jira connect ... | status | disconnect
+github              Token flow.   /github connect <token> | status | disconnect
+twitter             Token flow.   /twitter connect ... | status | disconnect
+```
+
+The exact `connect` fields per integration are defined in `INTEGRATION_REGISTRY` at [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py). Use `/help <integration>` to see what credentials it expects.
+
+### Agent-provided commands
+
+Skills can register commands at runtime via the agent command wrapper ([app/ui_layer/commands/builtin/agent_command.py](app/ui_layer/commands/builtin/agent_command.py)). These appear in `/help` alongside built-in commands. To audit what's currently registered, ask the user to run `/help` and paste the output, or read the live command registry from the running process.
+
+### When the user types a slash command
+
+If a user types a slash command and you receive the resulting task or message:
+- The runtime processes the command BEFORE you see it. Your role is to react to its outcome, not to re-execute.
+- For `/<skill_name>`, the runtime creates a task with the skill pre-selected. You take over from there.
+- For `/<integration> connect` or `/cred status`, the result lands in the chat as text. The user may then ask you to do something with the now-connected integration.
+- For `/clear`, `/clear_tasks`, `/reset`, `/exit`: state changes happen immediately. You may not have continuity with prior conversation/tasks after these.
+
+---
+
+## Configs
+
+The agent's behavior is shaped by JSON config files under [app/config/](app/config/). When you need to change settings about yourself (model, API keys, MCP servers, skills, schedules, integrations), you edit one of these files. The harness watches them and reloads automatically.
+
+This section is the source of truth for: every config file's full schema, what each key controls, the hot-reload mechanism, what does and does NOT take effect without restart, and the edit-and-verify workflow.
+
+### The six config files
+
+```
+app/config/settings.json              model, API keys, OAuth, cache, browser, memory          hot-reload
+app/config/mcp_config.json            MCP server registry                                     hot-reload
+app/config/skills_config.json         enabled / disabled skills                               hot-reload
+app/config/external_comms_config.json telegram + whatsapp listener configs                    hot-reload
+app/config/scheduler_config.json      cron schedules                                          hot-reload
+app/config/onboarding_config.json     first-run state                                         NOT watched
+```
+
+You may also encounter MCP server entries that point at standalone JSON files; those are imported at MCP load time and follow `mcp_config.json`'s lifecycle.
+
+### Editing protocol (memorize this)
+
+```
+1.  read_file <config_path>                       see current state
+2.  decide what to change
+3.  stream_edit <config_path> ...                 make the edit (preserves unrelated content)
+4.  wait ~0.5s for debounce                        the watcher coalesces rapid saves
+5.  verify the reload happened                    see "Verifying a reload" below
+6.  if no effect: check logs/<latest>.log for     [SETTINGS] / [MCP] / [CONFIG_WATCHER] errors
+    [CONFIG_WATCHER] / [MCP] / [SETTINGS] errors
+```
+
+Use `stream_edit`, never `write_file`, on configs. A whole-file rewrite risks losing unrelated keys the runtime relies on (e.g. `api_keys_configured` bookkeeping, your own `oauth` clients).
+
+If the file is malformed JSON after your edit, the reload fails and the previous in-memory config keeps running. Read the file back and fix the syntax. `[SETTINGS] JSONDecodeError` will appear in the log.
+
+### Hot-reload mechanism
+
+Source: [agent_core/core/impl/config/watcher.py](agent_core/core/impl/config/watcher.py) (`ConfigWatcher` singleton).
+
+```
+backend                  watchdog library if installed; polling (1s) fallback otherwise
+watch granularity        the watcher subscribes to each config file's PARENT DIRECTORY,
+                         then filters events by registered file path
+debounce                 0.5 seconds. Rapid saves within 500ms are coalesced into one reload.
+trigger                  on file modification:
+                           1. cancel any pending debounce timer for that path
+                           2. start a fresh 0.5s timer
+                           3. on timer fire, call the registered reload callback
+callback execution       sync callbacks run in the watcher thread. Async callbacks are
+                         scheduled on the main event loop via run_coroutine_threadsafe.
+log signature            "[CONFIG_WATCHER] Registered watch for <name>"  (at startup)
+                         "[CONFIG_WATCHER] Started watching config files"
+                         per-reload: "[SETTINGS] Reloaded ..." / "[MCP] Reloaded ..." etc.
+```
+
+### Per-config reload behavior
+
+Every watched config has a specific reload callback registered at startup ([app/agent_base.py](app/agent_base.py) `_initialize_config_watcher`):
+
+```
+settings.json
+  callback        settings_manager.reload + invalidate_settings_cache
+  effect          provider/model/API keys updated for the NEXT LLM call.
+                  An in-flight call uses the OLD config; the next turn uses the new one.
+  log signature   [SETTINGS] Reloaded ...
+
+mcp_config.json
+  callback        mcp_client.reload  (async)
+  effect          servers with enabled=true that are not connected get connected.
+                  servers that became enabled=false get disconnected.
+                  newly-added servers register their action set as mcp_<name>.
+                  tools appear in the next turn's action list (after action set is loaded).
+  log signature   [MCP] Loaded config with N server(s) ... [MCP] Connecting to '<name>' ...
+
+skills_config.json
+  callback        skill_manager.reload + ui_controller.sync_skill_commands
+  effect          skill discovery re-runs on skills/. Newly-enabled skills become
+                  selectable; disabled skills disappear. Slash commands for
+                  user-invocable skills are re-registered (/{skill_name} appears or vanishes).
+                  Effect on a running task: the active task keeps its locked skill list.
+                  New skills are only available to the NEXT task.
+  log signature   [SKILL] Reloaded skills_config ...
+
+external_comms_config.json
+  callback        registered after external_comms initialization
+  effect          telegram and whatsapp listeners start, stop, or reconfigure based on
+                  enabled / mode changes. Other platforms (discord, slack, etc.) are not
+                  in this file - they are managed by .credentials/ + /<integration> commands.
+  log signature   [EXT_COMMS] Reloaded ...
+
+scheduler_config.json
+  callback        scheduler.reload  (async)
+  effect          schedules re-parsed. New entries fire on their first matching window.
+                  Removed entries do not fire next cycle.
+                  Currently-firing tasks are not interrupted.
+  log signature   [SCHEDULER] Reloaded ...
+
+onboarding_config.json
+  callback        NONE (not watched).
+  effect          you do not edit this file. It is managed by the onboarding flow.
+                  If you change it manually, restart is required.
+```
+
+### What does NOT take effect on a config save
+
+- An action set already selected for an active task (locked at `task_start`).
+- An LLM call already in flight (uses the old config; next turn uses the new one).
+- A skill body / metadata change on a running task (skills are locked at task creation).
+- New built-in actions added by creating a new `.py` file under `app/data/action/` (code change, requires restart).
+- Changes to OS environment variables not stored in any config file (requires restart).
+- Code changes anywhere in `app/`, `agent_core/`, `agents/` (requires restart).
+
+If any of these apply, end the current task, restart only what's needed (often nothing - just start a new task), and the new config will be in force.
+
+### Verifying a reload
+
+By config:
+
+```
+settings.json
+  - check logs:  grep_files "[SETTINGS]" logs/<latest>.log -A 1
+  - or read back: read_file app/config/settings.json (confirm your edit landed)
+  - in next task: model/provider/api_key changes are observable when an LLM call fires
+
+mcp_config.json
+  - check logs:  grep_files "[MCP]" logs/<latest>.log -A 2
+  - look for:    "Connecting to '<server-name>'", "[StdioTransport] Starting subprocess"
+  - in next task: list_action_sets shows mcp_<server-name> as a registered set
+
+skills_config.json
+  - run /skill list (user-side) or
+  - call list_skills action  → confirms enabled/disabled state
+  - new /<skill_name> slash commands appear after sync_skill_commands fires
+
+external_comms_config.json
+  - check logs:  grep_files "[EXT_COMMS]" logs/<latest>.log -A 2
+  - if telegram/whatsapp enabled and started, expect connection success messages
+
+scheduler_config.json
+  - check logs:  grep_files "[SCHEDULER]" logs/<latest>.log -A 2
+  - call scheduled_task_list action  → confirms entries
+```
+
+If the log shows the reload fired but the change still isn't reflected: the change probably falls in "What does NOT take effect on a config save" above. End the current task or restart as appropriate.
+
+### Schemas
+
+The blocks below are dictionary-style: keys, valid values, and defaults. Read the actual JSON file (`read_file app/config/<name>.json`) when you need current values.
+
+<!-- schema:settings.json -->
+```
+File: app/config/settings.json
+
+version: string                  (CraftBot version this config was written for; do not edit)
+
+general:
+  agent_name: string             (the user-facing name of this agent, e.g. "CraftBot")
+  os_language: string            (BCP-47 / ISO code, e.g. "en")
+
+proactive:
+  enabled: bool                  (master switch for proactive workflow; if false,
+                                  proactive_heartbeat and planners are skipped)
+
+memory:
+  enabled: bool                  (master switch for memory_search and memory pipeline)
+  max_items: int                 (default 200; cap on MEMORY.md before pruning)
+  prune_target: int              (default 135; how many items remain after a prune)
+  item_word_limit: int           (default 150; words per stored memory item)
+
+model:
+  llm_provider: "openai" | "anthropic" | "google" | "byteplus" | "remote"
+  vlm_provider: same options
+  llm_model: string | null       (null = provider default; e.g. "claude-sonnet-4-5-20250929")
+  vlm_model: string | null
+  slow_mode: bool                (true throttles requests for rate-limited providers)
+  slow_mode_tpm_limit: int       (tokens per minute when slow_mode is true)
+
+api_keys:
+  openai: string                 (sk-...)
+  anthropic: string              (sk-ant-...)
+  google: string                 (Gemini API key)
+  byteplus: string
+
+endpoints:
+  remote_model_url: string       (for "remote" provider, e.g. Ollama base URL)
+  byteplus_base_url: string      (default https://ark.ap-southeast.bytepluses.com/api/v3)
+  google_api_base: string        (override for Gemini API base URL)
+  google_api_version: string     (override for Gemini API version)
+  remote: string                 (default http://localhost:11434; Ollama endpoint)
+
+oauth:
+  google:    { client_id, client_secret }     (used by /google invite OAuth flow)
+  linkedin:  { client_id, client_secret }     (used by /linkedin invite)
+  slack:     { client_id, client_secret }     (used by /slack invite)
+  notion:    { client_id, client_secret }     (used by /notion invite)
+  outlook:   { client_id }                    (used by /outlook invite)
+
+web_search:
+  google_cse_id: string          (Google Custom Search Engine ID for web_search action)
+
+cache:
+  prefix_ttl: int                (seconds; cache TTL for the system-prompt prefix)
+  session_ttl: int               (seconds; cache TTL for per-session state)
+  min_tokens: int                (skip caching prompts below this token count)
+
+browser:
+  port: int                      (default 7926; CraftBot browser frontend port)
+  startup_ui: bool               (auto-open browser at startup)
+
+api_keys_configured:             (BOOKKEEPING - reflects which keys are non-empty)
+  openai: bool
+  anthropic: bool
+  google: bool
+  byteplus: bool
+```
+<!-- /schema:settings.json -->
+
+<!-- schema:mcp_config.json -->
+```
+File: app/config/mcp_config.json
+
+mcp_servers: [
+  {
+    name: string                                   required, unique within file
+    description: string                            human-readable, shown to the LLM
+    transport: "stdio" | "sse" | "websocket"       default "stdio"
+    command: string                                required for stdio (e.g. "npx", "uv", "python")
+    args: [string]                                 stdio command arguments
+    url: string                                    required for sse / websocket
+    env: { KEY: VALUE }                            environment variables passed to the server process
+    enabled: bool                                  controls whether the server connects on load/reload
+    action_set_name: string                        default "mcp_<name>"; the action set tools register under
+  }
+]
+
+Patterns by transport:
+  NPX (Node):     transport="stdio"  command="npx"     args=["-y", "@org/server-name", ...optional-args]
+  Python (uv):    transport="stdio"  command="uv"      args=["run", "--directory", "<path>", "main.py"]
+  Python (pip):   transport="stdio"  command="python"  args=["-m", "<module>", ...args]
+  Remote SSE:     transport="sse"    url="http://localhost:3000/mcp"
+  Remote WS:      transport="websocket" url="ws://..."
+
+When a server is enabled and connects, all its tools become callable as actions
+under its action_set_name. To use them in a task, load that set via add_action_sets
+or via task_start's auto-selection.
+```
+<!-- /schema:mcp_config.json -->
+
+<!-- schema:skills_config.json -->
+```
+File: app/config/skills_config.json
+
+auto_load: bool                  default true; if false, no skills are loaded at startup
+enabled_skills: [skill_name]     skills available for selection / slash invocation
+disabled_skills: [skill_name]    explicitly turned off; loader sets enabled=false
+project_skills_dir: string       default "skills"; where SKILL.md directories are discovered
+
+Skills are discovered by scanning <project_skills_dir>/<name>/SKILL.md.
+A skill in disabled_skills is loaded but flagged disabled (the LLM does not see it).
+A skill not listed in either is loaded and enabled by default if auto_load is true.
+
+To enable a skill: move its name from disabled_skills to enabled_skills.
+To remove a skill entirely: also delete the directory under skills/.
+SKILL.md frontmatter fields: see ## Skills.
+```
+<!-- /schema:skills_config.json -->
+
+<!-- schema:external_comms_config.json -->
+```
+File: app/config/external_comms_config.json
+
+telegram:
+  enabled: bool                  master switch for the telegram listener
+  mode: "bot" | "mtproto"        bot = Bot API; mtproto = user-account API
+  bot_token: string              required for mode=bot (from @BotFather)
+  bot_username: string           the bot's @username (without the @)
+  api_id: string                 required for mode=mtproto (from my.telegram.org)
+  api_hash: string               required for mode=mtproto
+  phone_number: string           required for mode=mtproto (E.164 format)
+  auto_reply: bool               if true, incoming messages route to the agent
+
+whatsapp:
+  enabled: bool                  master switch for whatsapp listener
+  mode: "web" | "business"       web = WhatsApp Web (Playwright); business = Cloud API
+  session_id: string             web mode: cached browser session
+  phone_number_id: string        business mode (from Meta business)
+  access_token: string           business mode
+  auto_reply: bool
+
+NOTE: Other platforms (discord, slack, gmail, notion, linkedin, outlook,
+google, jira, github, twitter) do NOT live in this file.
+- Their credentials live under .credentials/<platform>.json.
+- OAuth client_id/secret for some live in settings.json's "oauth" section.
+- Connect/disconnect via /<platform> commands.
+See ## Integrations and ## Slash Commands.
+```
+<!-- /schema:external_comms_config.json -->
+
+<!-- schema:scheduler_config.json -->
+```
+File: app/config/scheduler_config.json
+
+enabled: bool                                master switch for the scheduler
+schedules: [
+  {
+    id: string                               unique identifier
+    name: string                             human-readable
+    instruction: string                      what the agent should do when fired
+    schedule: string                         natural language OR cron (see formats below)
+    enabled: bool                            individual schedule on/off
+    priority: int                            1-100, lower = higher priority
+    mode: "simple" | "complex"               task mode for the spawned task
+    recurring: bool                          true = stays after firing; false = one-shot
+    action_sets: [string]                    sets to load before the task fires
+    skills: [string]                         skills to inject before the task fires
+    payload: { type: string, ... }           passed to react()'s trigger.payload
+                                             type drives workflow routing (see ## Runtime):
+                                              "memory_processing", "proactive_heartbeat",
+                                              "proactive_planner", "scheduled", ...
+  }
+]
+
+Schedule formats (parser at app/scheduler/parser.py):
+  Natural:  "every day at 3am"
+            "every sunday at 5pm"
+            "every 30 minutes"
+            "every 3 hours"
+            "tomorrow at 9am"
+            "in 2 hours"
+            "in 30 minutes"
+            "at 3pm"
+            "immediate"
+  Cron:     "0,30 * * * *"
+            "0 7 * * *"
+            "0 8 1 * *"
+
+Built-in schedules (do NOT remove):
+  memory-processing  every day at 3am   payload.type="memory_processing"
+  heartbeat          0,30 * * *         payload.type="proactive_heartbeat"
+                                         skill: heartbeat-processor
+  day-planner        every day at 7am   payload.type="proactive_planner" scope=day
+  week-planner       every sunday at 5pm payload.type="proactive_planner" scope=week
+  month-planner      0 8 1 * *          payload.type="proactive_planner" scope=month
+```
+<!-- /schema:scheduler_config.json -->
+
+<!-- schema:onboarding_config.json -->
+```
+File: app/config/onboarding_config.json
+
+hard_completed: bool                  wizard finished (collected user_name, language, tone, etc.)
+soft_completed: bool                  conversational interview task finished
+hard_completed_at: ISO timestamp | null
+soft_completed_at: ISO timestamp | null
+user_name: string
+agent_name: string
+agent_profile_picture: string | null
+
+This file is NOT hot-reloaded. It is managed by the onboarding flow.
+Do NOT edit this file as part of normal operation.
+```
+<!-- /schema:onboarding_config.json -->
+
+### Common edits and recipes
+
+Switch LLM provider:
+```
+read_file app/config/settings.json
+stream_edit app/config/settings.json
+   model.llm_provider: "openai" → "anthropic"
+   model.llm_model: "<old>"     → "claude-sonnet-4-5-20250929"
+api_keys.anthropic must be set or the next LLM call fails (see ## Models).
+```
+
+Set an API key (when user provides one):
+```
+stream_edit app/config/settings.json
+   api_keys.<provider>: ""        → "<key>"
+   api_keys_configured.<provider>: false → true
+```
+
+Enable an MCP server already in the file:
+```
+stream_edit app/config/mcp_config.json
+   mcp_servers[i].enabled: false → true
+   if env requires a token, fill it
+```
+
+Add a new MCP server: see `## MCP` for the full recipe.
+
+Enable / disable a skill:
+```
+stream_edit app/config/skills_config.json
+   move <name> between enabled_skills and disabled_skills
+```
+
+Add a recurring schedule: prefer the `schedule_task` or `recurring_add` actions
+over editing scheduler_config.json directly. They validate the schedule expression.
+See `## Proactive`.
+
+### Pitfalls
+
+- JSON syntax errors silently keep the OLD config in memory. The reload fires, the
+  parser fails, the manager logs the error, and the previous state remains active.
+  Always verify after editing.
+- Editing `version` in settings.json does nothing useful and may confuse the next install.
+- `api_keys_configured` is bookkeeping. If you set a key, also flip the boolean.
+- `core` action set is hardcoded as always-included (see `## Action Sets`). You cannot
+  disable it via config.
+- The watcher subscribes to parent DIRECTORIES, so creating a new file in app/config/
+  is detected, but the file must be explicitly registered for any reload to fire.
+- Sandboxed actions (run_python with requirements) install their packages on first
+  call, NOT on config save. The config has no effect on action sandboxes.
+
+---
+
+## MCP
+
+MCP (Model Context Protocol) servers extend your tool inventory at runtime. Use MCP when you need a capability that no built-in action covers and no skill can compose. Each connected MCP server registers its tools as actions under a dedicated action set, callable through the same action interface as everything else.
+
+Code: [agent_core/core/impl/mcp/client.py](agent_core/core/impl/mcp/client.py) (`MCPClient`, singleton). Config: [app/config/mcp_config.json](app/config/mcp_config.json). Schema in `## Configs`.
+
+### How MCP fits in
+
+```
+mcp_config.json (your edit)
+        │
+        ▼
+MCPClient.initialize() at startup     OR    MCPClient.reload() on hot-reload
+        │
+        ▼
+for each enabled server:
+   spawn subprocess (stdio) OR open connection (sse/websocket)
+   discover its tools
+   register tools as actions in action set "mcp_<server_name>"
+        │
+        ▼
+to use: load the action set in a task (auto-selected, or via add_action_sets)
+        │
+        ▼
+LLM calls the tool just like any other action
+```
+
+The action set name is `mcp_<name>` by default, or whatever `action_set_name` is set to in the entry. After a successful connect, expect log lines like:
+
+```
+[MCP] Connecting to '<name>' (stdio): <command> <args>
+[MCP] Successfully connected to '<name>' with N tools
+[MCP] Registered N tools from server '<name>' into action set 'mcp_<name>'
+```
+
+### Pre-defined servers in this codebase
+
+The shipped `mcp_config.json` contains roughly 157 server entries (most `enabled: false`). Examples of always-shipped, commonly-enabled ones:
+
+```
+filesystem            @modelcontextprotocol/server-filesystem      file ops on cwd
+playwright-mcp        @playwright/mcp                              browser automation
+amadeus-hotels-mcp    travel API                                    hotels search
+github-mcp            @modelcontextprotocol/server-github           GitHub API
+```
+
+Categories present in the shipped config: filesystem, browser automation, calendar/email/notes, finance/markets/crypto, productivity, OS integrations, fitness, search, media, AI/image, e-commerce, dev tools, security, design, analytics, real estate. To enumerate: `grep_files '"name":' app/config/mcp_config.json` returns the full list.
+
+Before adding a NEW server, check the existing entries. The capability you need may already be there as `enabled: false` — flipping the flag is safer than adding a duplicate.
+
+### Add or enable a server (recipe)
+
+```
+1. read_file app/config/mcp_config.json
+2. Decide:
+     - The server already exists with enabled: false  → flip to true (skip to step 5)
+     - You need a new server                         → continue
+3. web_search "<capability> MCP server"
+   Common naming patterns:
+     @modelcontextprotocol/server-<name>      official servers
+     @<org>/<name>-mcp                        community servers
+     GitHub repos following the MCP spec
+4. stream_edit app/config/mcp_config.json
+   Append to mcp_servers array. Use the schema from ## Configs.
+   Set enabled: true. Set env keys (API tokens, etc.) if required.
+5. Wait ~0.5s for the watcher to debounce.
+6. Verify: see "Verifying a server is live" below.
+7. If verification fails, see "Failure modes and log signatures".
+```
+
+If the server's `env` requires a credential (API key, OAuth token, bot token), ASK THE USER for it. Do not invent values. Empty env strings are common defaults; the server will report missing-credential errors at first tool call.
+
+### Transport patterns
+
+```
+stdio (subprocess, most common)
+  transport: "stdio"
+  command:   "npx" | "uv" | "python" | "node" | <executable>
+  args:      [...]
+  env:       { KEY: VALUE }
+  url:       (omit)
+
+  Examples:
+    NPX:        command="npx",    args=["-y", "@modelcontextprotocol/server-filesystem", "."]
+    Python uv:  command="uv",     args=["run", "--directory", "C:/path/to/server", "main.py"]
+    Python pip: command="python", args=["-m", "<module_name>"]
+    Node:       command="node",   args=["<path-to-script.js>"]
+
+sse (server-sent events, remote)
+  transport: "sse"
+  url:       "http://localhost:3000/mcp"  or  "https://<host>/mcp"
+  command:   (omit)
+  env:       (often unused; the server handles its own auth)
+
+websocket (remote)
+  transport: "websocket"
+  url:       "ws://..."  or  "wss://..."
+```
+
+If the server author provides a `claude_desktop_config.json` snippet (common pattern), copy the `command`, `args`, and `env` directly. The schema is identical.
+
+### Verifying a server is live
+
+After enabling/adding, in order of cheapness:
+
+```
+1. grep the latest log for the server's name:
+     grep_files "[MCP].*<server_name>" logs/<latest>.log -A 1
+   Expect: "Successfully connected" + "Registered N tools".
+
+2. confirm the action set is registered:
+     call list_action_sets   → look for "mcp_<server_name>" in the result.
+
+3. load the set into your task:
+     call add_action_sets({"action_sets": ["mcp_<server_name>"]})
+     The new tools appear in the next turn's action list.
+
+4. call a tool from the set.
+   If it returns status=success, you're done. If status=error, the message
+   will usually point at credentials or remote-service issues.
+```
+
+If steps 1-2 fail, the server did not connect. Go to "Failure modes" below.
+If steps 3-4 fail, the server connected but tool execution is broken. Usually credentials.
+
+### Failure modes and log signatures
+
+```
+Symptom in log                                       Likely cause              Fix
+───────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+[MCP] Failed to load MCP config from <path>: ...     malformed JSON in         re-read mcp_config.json,
+                                                     mcp_config.json           fix syntax via stream_edit
+
+[MCP] Failed to connect to '<name>' - check          missing dep / wrong path  reproduce in run_shell:
+server configuration                                                            run the exact command +
+                                                                                args. Inspect stderr.
+
+[StdioTransport] Starting subprocess: <cmd>          subprocess started but    check the next few log
+followed by no "Successfully connected"              died early                lines for stderr from
+                                                                                the subprocess.
+
+[MCP] Exception connecting to '<name>': <type>: ...  any other connect-time    type tells you the class:
+                                                     error                     FileNotFoundError = command
+                                                                                missing; ConnectionError =
+                                                                                remote unreachable.
+
+server connected, tool calls return                  missing or wrong env      ask user for the key, set
+"unauthorized" / "missing API key" / "401"           variable                   it via /mcp env <name>
+                                                                                <KEY> <value>, or
+                                                                                stream_edit the env block.
+
+server connected, tool calls hang                    wrong transport (e.g.     fix transport in config.
+                                                     sse server marked stdio)
+
+server connected, tool calls succeed but always      remote rate limited       slow down or upgrade the
+return errors after first burst                                                remote-service plan.
+```
+
+Reproducing a stdio server outside the harness:
+
+```
+run_shell "<command> <args...>"   ← run literally what's in the config
+```
+
+If the subprocess fails standalone, the harness will fail too. Fix it standalone first.
+
+### Hot-reload behavior on save
+
+`MCPClient.reload(config_path)` does the following on each `mcp_config.json` save:
+
+```
+1. re-parse mcp_config.json
+2. for each currently-connected server:
+     if not in new config OR enabled=false in new config  →  disconnect
+3. for each enabled server in new config:
+     if not currently connected                            →  connect, register tools
+4. re-register all tools as actions
+5. return { success, disconnected[], connected[], failed[], total_tools }
+```
+
+Implications:
+- Toggling `enabled` cleanly connects or disconnects a single server.
+- Editing `env` for a connected server does NOT take effect until the server reconnects. Disable then re-enable, or call `mcp_client.reload()` after the file change.
+- Tasks already running keep their LOCKED action sets. New MCP tools become callable in the NEXT task or after `add_action_sets`.
+
+### Slash commands (user-side)
+
+```
+/mcp list                                  servers + connection state
+/mcp add <name> <command> [args...]        register a stdio server
+/mcp add-json <json>                       register from a full JSON entry
+/mcp remove <name>                         remove from config
+/mcp enable <name>                         flip enabled to true
+/mcp disable <name>                        flip enabled to false
+/mcp env <name> <KEY> <value>              set/update an env var
+```
+
+The agent does NOT call slash commands. If the user has not exposed an MCP server you need, edit the config directly via `stream_edit`.
+
+### When to choose MCP vs alternatives
+
+```
+Need a capability and...
+
+an existing built-in action covers it           →  use the action  (## Actions)
+a skill could compose existing actions          →  write/use a skill (## Skills)
+a third party already ships an MCP server       →  add MCP server (here)
+the user has a connected integration            →  use integration actions (## Integrations)
+nothing exists, you have to write code          →  author a new action (## Actions)
+```
+
+MCP is for capabilities you cannot get any other way without writing Python. The cost is process management, network, and an extra credential to maintain.
+
+### Permission and disclosure
+
+- Adding/enabling an MCP server modifies your runtime tool surface. Tell the user before doing it.
+- If `env` requires credentials, ASK first. Do not write empty placeholders to "test" — that just creates noise in logs and confuses the user.
+- After successful enable, summarize what tools the new server adds (count + a few names).
+
+---
+
+## Skills
+
+A skill is a markdown file with structured instructions that get injected into your prompt when selected. Skills exist for reusable workflows and codified domain knowledge that compose existing actions. Use a skill instead of an MCP server when no new tools are needed, just better instructions.
+
+Code: [agent_core/core/impl/skill/loader.py](agent_core/core/impl/skill/loader.py) (`SkillLoader`), [agent_core/core/impl/skill/config.py](agent_core/core/impl/skill/config.py) (`SkillMetadata`, `Skill`, `SkillsConfig`), [agent_core/core/impl/skill/manager.py](agent_core/core/impl/skill/manager.py) (`SkillManager` singleton).
+
+### What a skill is
+
+```
+A directory:                  skills/<name>/
+                              ├── SKILL.md         required
+                              └── <support files>  optional, referenced by SKILL.md
+
+A SKILL.md file:              YAML frontmatter (metadata)
+                              + markdown body (instructions injected into your prompt)
+
+When selected during a task:  body appended to your context until task_end.
+                              action-sets it declares are auto-loaded.
+                              /<name> slash command is registered (if user-invocable).
+```
+
+A skill is NOT a process, NOT a tool, NOT an action. It is text instructions plus a small bundle of action-set selections. The tools it uses are existing actions (built-in, MCP, integrations).
+
+### SKILL.md format
+
+```
+---
+name: <unique_id>                      required. Snake-case or kebab-case.
+description: <one paragraph>           required. The LLM reads this to decide
+                                        when to select. Be specific about WHEN
+                                        and WHAT triggers selection. Vague
+                                        descriptions never get selected.
+argument-hint: <hint>                  optional. Shown in /help when user types
+                                        /<name>. Example: "<city>" or "<file_path>".
+user-invocable: true                   optional, default true.
+                                        true = registers /<name> slash command.
+                                        false = only LLM-selectable mid-task.
+allowed-tools: [<action_name>, ...]    optional. If non-empty, ONLY these actions
+                                        are callable while the skill is active.
+                                        Empty / omitted = no restriction.
+action-sets: [<set_name>, ...]         optional. Auto-loaded when the skill is
+                                        selected. Use this to declare what tools
+                                        the skill needs (e.g. file_operations,
+                                        web_research, mcp_<server_name>).
+---
+
+# <Skill title>
+
+<Markdown body. Headings, lists, code blocks, examples - anything you'd put
+in a procedure document. This text is appended to your prompt for the
+duration of the task.>
+```
+
+Frontmatter parsing (regex `^---\s*\n(.*?)\n---\s*\n(.*)$`):
+- The file MUST start with `---` on the first line.
+- The frontmatter MUST be valid YAML.
+- Keys may use `kebab-case` OR `snake_case`. Both `argument-hint` and `argument_hint` work; same for the others.
+- If `name` is missing, the directory name is used.
+- If `description` is missing, the first non-heading paragraph of the body is used (truncated to 200 chars).
+
+### Variable substitution in the body
+
+When a skill is invoked with arguments (e.g. `/get-weather Tokyo`), the body's variables are substituted before injection ([SkillLoader.substitute_variables](agent_core/core/impl/skill/loader.py)):
+
+```
+$ARGUMENTS         the full argument string ("Tokyo")
+$ARGUMENTS[0]      first positional arg, 0-indexed
+$ARGUMENTS[1]      second positional arg
+$0, $1, $2 ...     shorthand for $ARGUMENTS[N]
+```
+
+If the skill is selected by the LLM mid-task (not via slash invocation), arguments are typically empty and these placeholders resolve to empty strings. Write skills to handle both invocation paths.
+
+### Discovery and enable flow
+
+```
+1. SkillLoader.discover_skills(search_dirs=[skills/], config=SkillsConfig)
+   scans <project_skills_dir>/<name>/SKILL.md files
+   parses frontmatter + body via FRONTMATTER_PATTERN
+2. for each parsed skill:
+     if name in disabled_skills (skills_config.json)  -> enabled=false
+     else                                             -> enabled=true
+3. enabled skills are presented to the LLM each task turn for selection
+4. user-invocable + enabled skills are registered as /<name> slash commands
+```
+
+Discovery runs at startup AND on every save of [app/config/skills_config.json](app/config/skills_config.json). The directory itself is NOT watched, so adding a brand-new skill directory requires either editing `skills_config.json` (any save triggers rediscovery) or running `/skill reload`.
+
+### How a skill gets selected for a task
+
+Two paths:
+
+**Path 1: User invocation via slash command.** When the user types `/<skill_name> [args]`:
+```
+1. The runtime calls do_create_task(...) with pre_selected_skills=[<skill_name>]
+2. LLM skill selection is BYPASSED (user already chose).
+3. LLM action-set selection still runs, then merges with skill's action-sets.
+4. Body is injected with $ARGUMENTS substituted.
+5. Task starts. Skill stays active for the entire task.
+```
+
+**Path 2: LLM selection.** When the user makes a request without slashing in:
+```
+1. do_create_task runs LLM skill+action-set selection (single LLM call).
+2. LLM picks zero, one, or more relevant skills based on their `description`.
+3. For each picked skill: body injected, action-sets merged, task starts.
+4. Skills picked stay active until task_end.
+```
+
+Skills CANNOT be swapped mid-task. To change skills, end the task and start a new one. Action sets CAN be swapped mid-task (see `## Action Sets`).
+
+### `allowed-tools` restriction
+
+When `allowed-tools` is non-empty in the frontmatter, the action filter narrows to ONLY those names while the skill is active. Use this for safety-critical skills where you want to prevent the LLM from straying. Leave empty (the default) for normal skills.
+
+### `action-sets` auto-loading
+
+When a skill is selected, every name in its `action-sets` is added to the task's action sets. The merger logic (in `do_create_task` at [app/internal_action_interface.py](app/internal_action_interface.py)):
+
+```
+final_action_sets = dedup(skill.action_sets + llm_selected_action_sets)
+```
+
+A skill that needs `web_research`, `file_operations`, and an MCP server should declare:
+```
+action-sets:
+  - web_research
+  - file_operations
+  - mcp_<server_name>
+```
+
+Don't rely on the LLM to pick the right sets. Declare them.
+
+### Adding a new skill
+
+Three paths, in order of preference:
+
+**1. Use the built-in `craftbot-skill-creator` skill.**
+```
+User runs:    /craftbot-skill-creator <name> <description>
+or LLM picks craftbot-skill-creator mid-task
+```
+This skill walks through the scaffold (writes the SKILL.md, sets up the directory, suggests action-sets). Most reliable path.
+
+**2. Install from a git repo.**
+```
+1. read_file app/config/skills_config.json       (avoid duplicates)
+2. web_search "<capability> SKILL.md github"     (or known skill repos)
+3. run_shell "git clone <url> skills/<name>"
+4. stream_edit app/config/skills_config.json
+     - move <name> from disabled_skills (if present) to enabled_skills
+     - or just add it to enabled_skills if new
+5. wait ~0.5s for hot-reload
+6. verify: /skill list (user-side) or call list_skills action
+```
+
+**3. Author by hand.**
+```
+1. mkdir skills/<name>
+2. write_file skills/<name>/SKILL.md
+   (use the format above; copy a similar existing skill as template)
+3. stream_edit app/config/skills_config.json to add to enabled_skills
+4. wait ~0.5s for hot-reload
+5. verify
+```
+
+After adding, the skill is available to the NEXT task. The currently-running task (if any) keeps its locked skill list.
+
+### Enable and disable
+
+A skill's enabled state is governed by its presence in `enabled_skills` vs `disabled_skills` in [app/config/skills_config.json](app/config/skills_config.json):
+
+```
+enabled_skills:    [<name>, ...]    skills available for LLM selection / slash invocation
+disabled_skills:   [<name>, ...]    explicitly OFF (loaded but invisible)
+not in either:                       loaded as enabled if auto_load=true (default)
+```
+
+Toggle via `stream_edit` on `skills_config.json`, OR via the user-side commands `/skill enable <name>` / `/skill disable <name>`. Both go through the same hot-reload path.
+
+### Verifying changes
+
+After enable / disable / install:
+
+```
+1. grep_files "[SKILL]" logs/<latest>.log -A 1     (confirm reload fired)
+2. action: list_skills                              (returns the live list)
+3. user-side: /skill list                           (same data, different UI)
+4. /<skill_name>                                    (only works if user-invocable=true
+                                                     AND enabled, else 404)
+```
+
+### Skill vs MCP vs action vs prompt - when to choose
+
+```
+Capability needs new code or external service                         -> MCP server (## MCP)
+Capability needs new code, isolated to the agent                      -> author an action (## Actions)
+Capability already exists, just needs orchestration / domain steps    -> skill (here)
+Just want to nudge the LLM with a one-off instruction                 -> put it in the user message,
+                                                                          NOT in a skill
+```
+
+Skills shine for: multi-step workflows ("first check X, then if Y, do Z"), domain expertise ("when generating slides, follow these design rules"), and codified procedures the LLM should follow exactly every time.
+
+### Pitfalls
+
+- A skill with a vague `description` will never get auto-selected. Be specific about triggers.
+- A skill that declares `action-sets` it doesn't actually need bloats the prompt.
+- A skill with `allowed-tools` that's too narrow will hit dead ends mid-task. Test before shipping.
+- Forgetting to add the skill to `enabled_skills` after a fresh install. It stays invisible. Always verify.
+- Editing a SKILL.md body of an installed skill: the change applies to the NEXT task. The currently-running task keeps the cached version.
+- Body too long: skill body is injected into every prompt for the task. Keep it tight.
+
+### Pre-shipped skills (sample)
+
+The shipped `skills/` directory contains around 100+ entries. Most are disabled by default; flip them via `enabled_skills` in `skills_config.json` to use. Examples currently enabled in this build:
+
+```
+get-weather                  weather lookup via Playwright + BBC Weather
+weather-check                similar pattern, alternative source
+craftbot-skill-creator       authoring new skills
+craftbot-skill-improve       refining an existing skill
+predict-stock-next-week      stock prediction workflow
+docx, pptx, xlsx, pdf        document generation per file format
+file-format                  format normalization
+playwright-mcp               browser automation steering
+living-ui-creator,
+living-ui-modify,
+living-ui-manager            Living UI project lifecycle
+compile-report-advance       multi-source report compilation
+```
+
+To enumerate the full installed set: `list_folder skills/` or `read_file app/config/skills_config.json`. To inspect a specific skill before enabling: `read_file skills/<name>/SKILL.md`.
+
+---
+
+## Integrations
+
+You can help the user connect external integrations directly through chat. Most token-based integrations can be fully driven by you: collect the credential from the user, call `connect_integration` with it, and the listener auto-starts. OAuth integrations require the user to run a slash command that opens a browser — your job is to walk them through it. Treat connecting an integration like helping a non-technical friend: tell them exactly where to go, what to copy, and what to paste back.
+
+Code: [app/external_comms/integration_settings.py](app/external_comms/integration_settings.py) (`INTEGRATION_REGISTRY`, `connect_integration_token`, `connect_integration_oauth`, `connect_integration_interactive`). Handlers: [app/credentials/handlers.py](app/credentials/handlers.py) (`INTEGRATION_HANDLERS`).
+
+### What's wired in
+
+11 integrations registered in `INTEGRATION_REGISTRY`. Each has an `auth_type` that determines how connection happens:
+
+```
+id                  display name        auth_type                description
+─────────────────   ─────────────────   ──────────────────────   ──────────────────────────────
+google              Google Workspace    oauth                    Gmail, Calendar, Drive
+slack               Slack               both (oauth + token)     Team messaging
+notion              Notion              both (oauth + token)     Notes and databases
+linkedin            LinkedIn            oauth                    Professional network
+discord             Discord             token                    Community chat
+telegram            Telegram            token_with_interactive   Messaging platform
+whatsapp            WhatsApp            interactive (QR scan)    Messaging via Web
+whatsapp_business   WhatsApp Business   token                    WhatsApp Cloud API
+jira                Jira                token                    Issue tracking
+github              GitHub              token                    Repos, issues, PRs
+twitter             Twitter/X           token                    Tweets, timeline
+```
+
+To enumerate at runtime: call the `list_available_integrations` action. To check what's already connected: `check_integration_status`.
+
+### The agent's connection toolkit (actions)
+
+```
+list_available_integrations()                  → returns full registry + connected state for each
+check_integration_status(integration_id)       → status of one integration
+connect_integration(integration_id, ...)       → token-based connect (requires credentials)
+disconnect_integration(integration_id)         → remove connection
+```
+
+`connect_integration` is the workhorse for token-based flows. The exact required fields depend on the integration. Read [app/data/action/integration_management.py](app/data/action/integration_management.py) for the action's input_schema.
+
+### Auth-type playbook
+
+The user just asked you to connect an integration. Here's what you do for each `auth_type`:
+
+```
+auth_type "token"
+  Driven entirely from chat by you. Steps:
+    1. Tell user where to obtain the credential (links + scopes below).
+    2. User pastes the credential in chat.
+    3. You call connect_integration(integration_id, credentials={...}).
+    4. Verify with check_integration_status.
+
+auth_type "oauth"
+  Cannot be fully driven from chat. The user must run a slash command that
+  opens a browser. Steps:
+    1. Confirm settings.json has the right oauth.<platform> client_id and
+       client_secret. If empty, tell the user to register an OAuth app at
+       the platform's developer console (links below) and paste the IDs.
+       You can stream_edit settings.json once they paste.
+    2. Tell user: "Run /<platform> login (or /<platform> invite). It will
+       open a browser. Authorize, then come back."
+    3. Wait for user to confirm. Do NOT poll.
+    4. Call check_integration_status to confirm connection.
+
+auth_type "both"
+  Two paths. Pick based on user preference:
+    - User has CraftOS bot/app available     → /<platform> invite (OAuth)
+    - User has their own bot token / app     → connect_integration with token
+  Default to whichever the user already mentioned. If unclear, ask.
+
+auth_type "interactive" (whatsapp)
+  Requires a QR scan from the user's phone. Steps:
+    1. Tell user: "Run /whatsapp login. A QR code will appear. Scan it with
+       WhatsApp on your phone (Settings → Linked Devices → Link a Device)."
+    2. Wait for user to confirm scan.
+    3. Verify with check_integration_status.
+
+auth_type "token_with_interactive" (telegram)
+  Token is the primary path; the same as "token". Telegram has additional
+  user-account flows (login-user) that are interactive — only invoke if the
+  user explicitly wants user-account access (not bot).
+```
+
+Never invent a credential. If the user has not provided one, ask. If the user pastes something that doesn't match the expected format, point out what was expected before calling `connect_integration`.
+
+### Required fields and where to obtain them
+
+The fields each token integration needs (from `INTEGRATION_REGISTRY`):
+
+```
+slack
+  bot_token         (required, "xoxb-..." — Bot User OAuth Token)
+  workspace_name    (optional, friendly label)
+  Where to get it:
+    1. Go to https://api.slack.com/apps → Create New App (from scratch).
+    2. OAuth & Permissions → add scopes (chat:write, channels:read,
+       channels:history, users:read, etc. depending on use).
+    3. Install to Workspace → copy the "Bot User OAuth Token" (xoxb-...).
+
+notion
+  token             (required, "secret_..." — Internal Integration Secret)
+  Where to get it:
+    1. Go to https://www.notion.so/my-integrations → New integration.
+    2. Pick a workspace and a name. Submit.
+    3. Copy the "Internal Integration Secret".
+    4. In Notion, share the relevant pages/databases with the integration
+       (the "..." menu on each page → Add connections).
+
+discord
+  bot_token         (required — Bot Token from a Discord application)
+  Where to get it:
+    1. Go to https://discord.com/developers/applications → New Application.
+    2. Bot tab → Add Bot → "Reset Token" → copy.
+    3. Enable required intents (Message Content, Server Members, etc.).
+    4. OAuth2 → URL Generator → bot scope + permissions → invite bot to server.
+
+telegram (bot)
+  bot_token         (required — from @BotFather)
+  Where to get it:
+    1. On Telegram, message @BotFather.
+    2. /newbot → set name and username (must end in "bot").
+    3. @BotFather replies with the token. Copy and paste.
+
+whatsapp_business
+  access_token      (required — Meta Cloud API access token)
+  phone_number_id   (required — phone number ID from Meta Business)
+  Where to get it:
+    1. Go to https://developers.facebook.com → My Apps → Create App
+       (Business type) → Add Product → WhatsApp.
+    2. From the WhatsApp config: copy the temporary access token AND the
+       phone_number_id of the test number (or your own once verified).
+    3. For production, generate a permanent token via System User.
+
+jira
+  domain            (required — e.g. mycompany.atlassian.net, no https)
+  email             (required — your Atlassian account email)
+  api_token         (required — Atlassian API token)
+  Where to get it:
+    1. Go to https://id.atlassian.com/manage-profile/security/api-tokens.
+    2. Create API token → label it → copy.
+
+github
+  access_token      (required — Personal Access Token, "ghp_..." or "github_pat_...")
+  Where to get it:
+    1. Go to https://github.com/settings/tokens → Generate new token.
+    2. For full repo access, classic token with repo, workflow, read:org scopes;
+       fine-grained tokens work for specific repos.
+    3. Copy the token (only shown once).
+
+twitter
+  api_key             (required — Consumer Key)
+  api_secret          (required — Consumer Secret)
+  access_token        (required)
+  access_token_secret (required)
+  Where to get it:
+    1. Go to https://developer.twitter.com → Projects & Apps → create an app.
+    2. Keys and tokens tab: regenerate Consumer Keys, then Access Token and Secret.
+    3. Apps need at least Read+Write user-context permissions for posting.
+```
+
+For OAuth integrations (no fields, but client_id/client_secret in `settings.json` `oauth.<platform>`):
+
+```
+google
+  client_id, client_secret in settings.json → oauth.google
+  Where to get it:
+    1. Go to https://console.cloud.google.com/apis/credentials.
+    2. Create OAuth 2.0 Client ID → Desktop app or Web application.
+    3. Copy client_id and client_secret.
+    4. Enable APIs you need: Gmail API, Google Calendar API, Google Drive API.
+    5. After saving keys to settings.json, user runs /google login.
+
+linkedin
+  client_id, client_secret in settings.json → oauth.linkedin
+  Where to get it:
+    1. Go to https://www.linkedin.com/developers/apps.
+    2. Create app → set redirect URL (the CraftBot OAuth callback).
+    3. Verify app, request access to required products.
+    4. Copy Client ID and Client Secret.
+    5. After saving keys to settings.json, user runs /linkedin login.
+
+slack OAuth (alternate to bot token)
+  client_id, client_secret in settings.json → oauth.slack
+  User runs /slack invite (uses CraftOS-hosted app) or set up your own.
+
+notion OAuth (alternate to integration token)
+  client_id, client_secret in settings.json → oauth.notion
+  Most users prefer the token path (simpler).
+```
+
+### End-to-end chat-driven connection example
+
+A canonical chat-driven flow for `github`:
+
+```
+User: "connect my github"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", task_description="Connect user's GitHub")
+
+Agent (inside the task):
+  send_message: "I can connect GitHub. I'll need a Personal Access Token.
+                 To create one:
+                 1. Go to https://github.com/settings/tokens
+                 2. Click 'Generate new token (classic)'
+                 3. Pick the scopes you need (repo, workflow, read:org for full access)
+                 4. Generate and copy the token (it's only shown once)
+                 Paste it here when ready."
+
+User: "ghp_abc123xyz..."
+
+Agent:
+  connect_integration(
+    integration_id="github",
+    credentials={"access_token": "ghp_abc123xyz..."}
+  )
+  → returns {status: "success", message: "..."}
+
+Agent:
+  check_integration_status(integration_id="github")
+  → confirms connected, lists account name
+
+  send_message: "Connected. You're authenticated as <username>. You can now
+                 ask me to read your repos, manage issues, or open PRs."
+  task_end
+```
+
+For `oauth` integrations the analogous flow:
+
+```
+User: "connect my google account"
+
+Agent:
+  Check settings.json oauth.google. If client_id/client_secret are empty,
+  walk the user through registering an OAuth app at console.cloud.google.com,
+  collect the IDs, stream_edit settings.json, then continue.
+
+  send_message: "Now run `/google login` in chat. A browser will open.
+                 Authorize CraftBot, then come back here and tell me when
+                 you're done."
+
+User: "done"
+
+Agent:
+  check_integration_status(integration_id="google")
+  → if connected: confirm + list scopes/account
+  → if not: ask user to retry, mention common issues (popup blocked,
+            wrong account picked, scopes denied)
+```
+
+### Listener auto-start
+
+After a successful `connect_integration` call, listeners auto-start for platforms that support push-style messaging. From `PLATFORM_MAP`:
+
+```
+whatsapp     → whatsapp_web listener
+telegram     → telegram_bot AND telegram_user listeners
+google       → google_workspace listener
+jira         → jira listener
+github       → github listener
+twitter      → twitter listener
+```
+
+For `slack`, `notion`, `discord`, `linkedin`, `outlook`, `whatsapp_business`: connection works but listener-style auto-reply is not configured at this layer (some are handled separately via `external_comms_config.json` for telegram/whatsapp specifically).
+
+### Verifying a connection
+
+After any connect attempt:
+
+```
+1. check_integration_status(integration_id)         → returns success + account display
+2. /cred status (user-side)                          → overview of all integrations
+3. grep_files "[<platform>]" logs/<latest>.log     → look for connect / auth errors
+```
+
+If `check_integration_status` returns "Not connected" right after a successful `connect_integration` call, something is wrong. Common: the credential validated but the listener failed to start (check logs for that platform's tag).
+
+### Disconnect
+
+```
+disconnect_integration(integration_id, account_id?)
+```
+
+`account_id` is optional. Pass it when there are multiple accounts on one platform (e.g. multiple Slack workspaces) and you want to keep the others. Omit to disconnect everything for that integration.
+
+The user can also `/<platform> disconnect [account_id]`.
+
+### Common failure modes
+
+```
+Symptom                                            Likely cause              Fix
+─────────────────────────────────────────────────  ────────────────────────  ──────────────────────────
+"Bot token is required" / "Token is required"      missing credential        ask user, retry
+                                                   in connect_integration
+
+connect succeeds, but tool calls return            scope insufficient        user re-creates token
+"Forbidden" / "Insufficient scope"                                            with proper scopes
+
+oauth connect: browser doesn't open                missing client_id/secret  walk user through
+                                                   in settings.json          registering OAuth app
+                                                                              and pasting IDs
+
+oauth connect: "redirect_uri_mismatch"             redirect URL wrong in     fix redirect URL in
+                                                   the developer console     developer console
+
+whatsapp QR: timeout                               user did not scan in time tell user to retry,
+                                                                              ensure phone has network
+
+jira: 401 / 403 on tool calls                      domain or email wrong     user re-checks domain
+                                                                              format and Atlassian email
+
+twitter: invalid signature                         API tier doesn't allow    user upgrades Twitter API
+                                                   the operation             tier (free is read-only)
+
+connection works once, fails next session          token expired (some       user regenerates and
+                                                   GitHub fine-grained       reconnects
+                                                   tokens have short TTL)
+```
+
+When in doubt: read the action's error message in full, then check `logs/<latest>.log` for the integration's tag.
+
+### When to use integration actions vs MCP
+
+Some integrations have BOTH built-in actions (via this section's connection flow) AND a corresponding MCP server (e.g. `github`, `notion`, `slack`). Pick:
+
+```
+You need basic CRUD via the user's account                    → built-in integration (here)
+You need rich tool surface, custom workflows, or a feature
+the built-in action doesn't expose                            → MCP server (## MCP)
+The user has both connected                                   → use the integration first;
+                                                                 fall back to MCP if missing a verb
+```
+
+The built-in integrations cover the common 80%; MCP covers the long tail.
+
+### Permission and disclosure
+
+- ALWAYS tell the user what credentials you need and where to get them. Never paste a vague "give me your token".
+- ALWAYS confirm the credential format roughly matches before submitting (e.g., GitHub PAT starts with `ghp_` or `github_pat_`). If it doesn't, ask the user to verify.
+- ALWAYS mask tokens in your replies. Don't echo back the full credential — use a prefix or a `...` truncation.
+- ALWAYS verify connection success before declaring victory.
+- NEVER write the token to memory, MEMORY.md, USER.md, or chat history beyond the immediate connect step. The handler stores it under `.credentials/<platform>.json` (see `## File System` for the do-not-print rule).
+
+### Using an integration during a task
+
+Connecting is one job; *using* an integration in a task is another. Each integration's source directory may carry an `INTEGRATION.md` reference doc — non-obvious workflows, identity formats, error meanings, and quirks that don't fit in action `input_schema` descriptions.
+
+Two location patterns (try the first; fall back to the second):
+- `craftos_integrations/integrations/<name>/INTEGRATION.md` — directory-style integrations (e.g. [whatsapp_web](craftos_integrations/integrations/whatsapp_web/INTEGRATION.md))
+- `craftos_integrations/integrations/<name>.md` — single-file integrations (e.g. [discord.md](craftos_integrations/integrations/discord.md), [gmail.md](craftos_integrations/integrations/gmail.md), [slack.md](craftos_integrations/integrations/slack.md))
+
+**Consult one before asking the user for input the integration could probably look up itself.** Common case: the user says "send a WhatsApp message to X" and you're tempted to ask for their own phone number — don't. The bridge already knows the logged-in user's identity. The INTEGRATION.md spells out which action returns it.
+
+Other times to grep an INTEGRATION.md:
+- An action returns an error you don't understand.
+- A workflow needs more than one action and you're unsure of the order or which fields to pass between them.
+- A field value looks unfamiliar (e.g. ends in `@lid`, `@c.us`, `@g.us`) and you're tempted to "clean it up" — these are real identity formats; pass them verbatim.
+
+If the file is missing for an integration you need, fall back to grepping the integration's source directory.
+
+---
+
+## Models
+
+You generate every response through an LLM. The user can ask you to change provider or model in chat, and you can drive that change. This section covers: providers, the model registry, LLM vs VLM vs embedding, the right way to switch (with a critical gotcha), per-provider caching strategy, and rate-limit handling.
+
+Code: [agent_core/core/impl/llm/interface.py](agent_core/core/impl/llm/interface.py) (`LLMInterface`), [agent_core/core/models/model_registry.py](agent_core/core/models/model_registry.py) (`MODEL_REGISTRY`), [app/models/factory.py](app/models/factory.py) (`ModelFactory.create`), [app/ui_layer/settings/model_settings.py](app/ui_layer/settings/model_settings.py) (`PROVIDER_INFO`).
+
+### Three interface types
+
+The same provider serves up to three "interfaces":
+
+```
+LLM         text generation. The main chat brain. Required.
+VLM         vision-language model. Used for image actions (describe_image, OCR).
+EMBEDDING   text embedding. Used for memory_search semantic indexing.
+```
+
+Each interface picks its model independently. `settings.json` `model.llm_provider` and `model.vlm_provider` can point at different providers if you want (e.g., `anthropic` for text, `gemini` for vision).
+
+### Providers and what they support
+
+From [MODEL_REGISTRY](agent_core/core/models/model_registry.py):
+
+```
+provider     LLM default model            VLM default model           EMBEDDING default        notes
+─────────    ──────────────────────       ──────────────────────      ──────────────────────   ─────────────────────────────
+openai       gpt-5.2-2025-12-11           gpt-5.2-2025-12-11          text-embedding-3-small   OpenAI-hosted
+anthropic    claude-sonnet-4-5-20250929   claude-sonnet-4-5-20250929  (none — no embedding)    Claude models
+gemini       gemini-2.5-pro               gemini-2.5-pro              text-embedding-004       Google Gemini
+byteplus     seed-1-6-250915              seed-1-6-250915             skylark-embedding-...    BytePlus-hosted
+remote       llama3.2:3b                  llava:7b                    nomic-embed-text         Ollama or OpenAI-compat
+deepseek     deepseek-chat                (none)                      (none)                   text only
+moonshot     moonshot-v1-8k               (none)                      (none)                   text only
+grok         grok-3                       grok-4-0709                 (none)                   xAI
+minimax      MiniMax-Text-01              (none)                      (none)                   text only
+```
+
+If you set `model.llm_model: null` in settings.json, the default from MODEL_REGISTRY is used. Set an explicit string to override.
+
+A provider with `(none)` for VLM cannot be used as `vlm_provider`. If the user asks for vision but only has a text-only provider configured, tell them to set a separate `vlm_provider` (or use `byteplus` / `anthropic` / `openai` / `gemini` for vision).
+
+### Provider-name vs settings-key mismatch (gotcha)
+
+The provider names used in code and in `model.llm_provider` are not always identical to the `api_keys.<key>` names:
+
+```
+provider name   settings.json api_keys field   /provider command alias
+─────────────   ─────────────────────────       ──────────────────────
+openai          api_keys.openai                 openai
+anthropic       api_keys.anthropic              anthropic
+gemini          api_keys.google                 gemini    (note: provider name is "gemini" but the key is stored under "google")
+byteplus        api_keys.byteplus               byteplus
+deepseek        api_keys.deepseek               deepseek
+grok            api_keys.grok                   grok
+remote          (none — uses endpoints.remote)  remote
+```
+
+When setting an API key for Gemini, edit `api_keys.google`, NOT `api_keys.gemini`. Same translation in the `api_keys_configured` block.
+
+### Model section schema (in settings.json)
+
+```
+model:
+  llm_provider:        string        e.g. "anthropic"
+  vlm_provider:        string        e.g. "anthropic"  (often same as llm_provider)
+  llm_model:           string|null   null = use MODEL_REGISTRY default for the provider
+  vlm_model:           string|null   null = use MODEL_REGISTRY default
+  slow_mode:           bool          true = throttle requests to avoid 429s
+  slow_mode_tpm_limit: int           tokens per minute when slow_mode is true (e.g. 25000)
+```
+
+Full settings.json schema is in `## Configs`.
+
+### How LLMInterface picks the model
+
+At construction (and on `reinitialize_llm`), `ModelFactory.create(provider, interface, model_override, ...)`:
+
+```
+1. Looks up the provider in MODEL_REGISTRY[provider][interface].
+2. If model_override is set, uses it. Otherwise uses the registry default.
+3. Wires up the right client: OpenAI SDK, Anthropic SDK, Gemini client, BytePlus
+   wrapper, or Ollama HTTP for "remote".
+4. Returns ctx with provider, model, client/handles, base URL, etc.
+```
+
+The LLMInterface is constructed ONCE at startup (and reconstructed by `reinitialize_llm`). It is NOT recreated when settings.json is hot-reloaded. This is the most important gotcha in this section — see "Switching provider or model" below.
+
+### Switching provider or model — through chat
+
+The user asks: "switch to GPT-4" or "use Gemini" or "I'd like to try Claude".
+
+There are TWO mutation paths. Pick the right one based on what's changing:
+
+**Path A: Same-provider model swap (e.g. claude-sonnet-4 → claude-opus-4)**
+
+Edit `settings.json` and the change applies on the NEXT LLM call. The cache invalidates on save; the existing client uses the new model name from the next call onward.
+
+```
+1. read_file app/config/settings.json
+2. stream_edit:
+     model.llm_model: "<old>" → "<new>"
+     (also model.vlm_model if user wants vision swap)
+3. wait ~0.5s for hot-reload
+4. send_message confirming the swap took effect on next turn
+```
+
+**Path B: Provider switch (e.g. anthropic → openai)**
+
+`stream_edit` ALONE is not enough. The LLMInterface holds the old provider's client. You must trigger `reinitialize_llm`, which is exposed only via the `/provider` slash command.
+
+```
+1. Ensure api_keys.<settings_key> for the new provider is set.
+   Remember the gemini → "google" name translation.
+   If empty: ask the user for a key, then stream_edit api_keys + api_keys_configured.
+2. Tell the user to run:    /provider <name> [<api_key>]
+   Examples:    /provider openai sk-...
+                /provider anthropic
+                /provider gemini AIza...
+3. The slash command:
+     - saves to settings.json (settings, api_keys, env)
+     - calls agent.reinitialize_llm(<provider>) which rebuilds the LLMInterface
+4. Verify by waiting for the next LLM-driven response; mention the new provider
+   is in effect.
+```
+
+DO NOT just stream_edit `model.llm_provider` and call it done. The cache will say the new provider, but the LLMInterface will still use the old one until reinit. Symptoms of getting this wrong: replies still come from the old model, or LLMConsecutiveFailureError if the old client now lacks credentials.
+
+If the user cannot or will not run the slash command, the alternative is restarting CraftBot. State that explicitly.
+
+### Setting a missing API key (no provider switch)
+
+If the user just provides a new key for the CURRENT provider (e.g., they updated their Anthropic key):
+
+```
+1. stream_edit settings.json
+     api_keys.<settings_key>: "<old or empty>" → "<new>"
+     api_keys_configured.<settings_key>: false → true
+2. Hot-reload picks up the new key on next LLM call.
+3. If unsure whether the existing client cached the old key, recommend the user
+   run /provider <current> <new_key> to rebuild the client cleanly.
+```
+
+### Connection testing
+
+Before declaring the switch worked, verify. There's a built-in test using
+[app/config/connection_test_models.json](app/config/connection_test_models.json) (a tiny model + 1-token request per provider).
+
+```
+1. read_file app/config/connection_test_models.json   (see what model is used to test)
+2. test_provider_connection(provider, api_key)        helper at app/models
+                                                       (or wait for the user's first
+                                                        response to confirm)
+```
+
+The cheapest verification is just sending a `send_message` and waiting for the reply to come back without `LLMConsecutiveFailureError`.
+
+### Slow mode (rate-limit handling)
+
+If the user hits 429s (provider rate limit):
+
+```
+slow_mode: true                  pace requests
+slow_mode_tpm_limit: <N>         tokens per minute target. Common: 25000 for Anthropic free.
+```
+
+Set both. The throttle is internal to LLMInterface. After enabling, no further changes needed for the user — requests just take longer.
+
+### Per-provider caching (KV cache strategy)
+
+The harness applies different caching strategies per provider. You don't manage this directly, but knowing it helps explain cost/latency to the user:
+
+```
+provider      cache type                                managed by
+─────────     ───────────────────────────────────────   ───────────────────────────
+anthropic     ephemeral cache_control with extended TTL agent_core (built-in)
+gemini        explicit context cache (file-based)        GeminiCacheManager
+byteplus      session cache (server-side, prefix-based) BytePlusCacheManager
+openai        prompt_cache_key (automatic)               provider auto
+deepseek      prompt_cache_key                           provider auto
+grok          prompt_cache_key                           provider auto
+remote        no cross-request caching                   n/a
+```
+
+Cache TTLs come from `cache.prefix_ttl` and `cache.session_ttl` in settings.json. `cache.min_tokens` skips caching for short prompts.
+
+### Endpoint overrides
+
+In `settings.json` `endpoints`:
+
+```
+remote_model_url       base URL for "remote" provider (Ollama or OpenAI-compat)
+remote                 alternate endpoint for remote (default http://localhost:11434)
+byteplus_base_url      defaults to https://ark.ap-southeast.bytepluses.com/api/v3
+google_api_base        override for Gemini API base URL
+google_api_version     override for Gemini API version
+```
+
+Use these for self-hosted, regional endpoints, or non-default Gemini API versions. For most users, leave defaults.
+
+### Consecutive-failure circuit breaker
+
+`LLMInterface._max_consecutive_failures = 5`. After 5 consecutive failed LLM calls, `LLMConsecutiveFailureError` is raised, the active task is auto-cancelled, and `LLM_FATAL_ERROR` UI event fires. Counter resets on a successful call.
+
+Common triggers: bad API key, expired key, model name typo, rate limit storm, network outage. See `## Errors` for the recovery rules. After fixing the cause, the user must START A NEW TASK (the cancelled one is gone).
+
+### Picking the right model for a job
+
+When the user is undecided:
+
+```
+Goal                                          Suggested provider
+──────────────────────────────────────────    ──────────────────────────
+General chat / coding / reasoning             anthropic (claude-sonnet-4-5)
+                                              openai (gpt-5.2)
+Vision / image understanding                  any of: anthropic, openai, gemini, byteplus, grok
+Long-context document analysis                gemini (1-2M context)
+                                              anthropic with extended cache
+Cheap bulk reasoning                          deepseek
+                                              byteplus
+Air-gapped / offline                          remote (Ollama)
+                                              point to local llama / qwen / mistral
+Strict cost control                           gemini (free tier)
+                                              deepseek (low per-token)
+```
+
+This list is opinion, not authoritative. The user has the final say.
+
+### Pitfalls
+
+- Editing `model.llm_provider` in settings.json without running `/provider` to reinitialize. The cache says new, the live LLM uses old. Always do Path B.
+- Setting `api_keys.gemini` instead of `api_keys.google`. The Gemini provider reads from the `google` key (settings_key mismatch). Same for `api_keys_configured`.
+- Choosing a `vlm_provider` whose `MODEL_REGISTRY` entry has `VLM: None`. Vision actions will fail.
+- Empty `api_keys.<provider>` for a non-remote provider triggers `MSG_AUTH` on the first call. Always check before switching.
+- Forgetting to update `api_keys_configured` when adding a key. UI bookkeeping breaks; LLM still works.
+- Running `/provider <name>` with a key but the key is for the wrong provider (e.g., pasting Anthropic key after `/provider openai`). The error surfaces on the first call. Verify keys match.
+- Switching to `remote` (Ollama) without `endpoints.remote_model_url` configured. The factory tries `http://localhost:11434` by default; if Ollama isn't running, every call fails.
+
+### Permission and disclosure
+
+- Always confirm with the user before switching provider. The active task may have cached state that doesn't transfer.
+- Always mask API keys in chat (`sk-***...***abcd`). Echo the prefix and last 4 only.
+- After a switch, send a brief confirmation: provider, model, whether vision is supported.
+- Don't change models without being asked. Stick with what the user configured.
+
+---
+
+## Memory
+
+Memory is your long-term recall. It is RAG-backed (semantic search over a vector index), not text-grep over MEMORY.md. Items reach MEMORY.md only after the daily memory-processing pipeline distills them from the event stream. You read memory via the `memory_search` action; you do NOT write MEMORY.md directly.
+
+Code: [agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) (`MemoryManager`), [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) (incremental re-indexing), [app/data/action/memory_search.py](app/data/action/memory_search.py) (action).
+
+### The pipeline
+
+```
+1. Action / message / system event happens
+        |
+        v
+2. EventStreamManager appends to EVENT.md           (full chronological log)
+        |
+        v
+3. EventStreamManager appends filtered subset to    (memory pipeline staging
+   EVENT_UNPROCESSED.md                              buffer; see filter below)
+        |
+        v
+4. Daily 3am: scheduler fires payload.type=         (or on startup if buffer
+   "memory_processing" trigger                       is non-empty)
+        |
+        v
+5. Agent runs the memory-processor skill            (set_skip_unprocessed_logging
+   reads EVENT_UNPROCESSED.md                        is True so the task's own
+   scores each event with Decision Rubric            events do not loop back)
+   distills passing events to MEMORY.md
+        |
+        v
+6. EVENT_UNPROCESSED.md is cleared
+        |
+        v
+7. memory_file_watcher detects MEMORY.md changed,
+   triggers MemoryManager.update() to reindex the
+   ChromaDB collection
+```
+
+EVENT_UNPROCESSED.md filter (events NOT staged): `action_start`, `action_end`, `todos`, `error`, `waiting_for_user`. The pipeline focuses on user-facing dialogue and important state changes. See `## File System` for full details.
+
+The Decision Rubric (Impact + Risk + Cost + Urgency + Confidence, each 1-5, threshold >= 18) lives in [PROACTIVE.md](agent_file_system/PROACTIVE.md). Do NOT duplicate it elsewhere.
+
+### MEMORY.md format
+
+```
+[YYYY-MM-DD HH:MM:SS] [type] content
+```
+
+Type values:
+```
+capability          a new tool, MCP server, or skill became available
+project             ongoing work the user is doing
+workspace           workspace contents or organization
+focus               what the user is currently focused on
+preference          a stable user preference (also goes to USER.md often)
+analysis            distilled insight from a past task
+user_complaint      something the user objected to (avoid repeating)
+system_warning      a non-fatal warning the agent should remember
+system_limit        a known limit (rate limit, model quota, etc.)
+```
+
+One fact per line. Multi-line entries break the parser.
+
+### How memory_search works
+
+`memory_search(query, top_k)` is a vector search via ChromaDB ([app/data/action/memory_search.py](app/data/action/memory_search.py)):
+
+```
+input:
+  query            string. Natural-language question or topic.
+  top_k            int, default 5. Maximum results to return.
+
+output:
+  status           "ok" | "error"
+  results          list of memory pointers:
+                     [
+                       {
+                         chunk_id:        "MEMORY.md_memory_3"
+                         file_path:       "MEMORY.md"
+                         section_path:    "Memory"
+                         title:           "<section title>"
+                         summary:         "<first ~150 chars of the chunk>"
+                         relevance_score: 0.0-1.0 (higher = more relevant)
+                       },
+                       ...
+                     ]
+  count            int
+```
+
+Pointers are LIGHTWEIGHT references, not full content. To read the full chunk, `read_file <file_path>` and find the section, OR call the manager's `retrieve_full_content(chunk_id)` if exposed via an action.
+
+Relevance score is normalized from ChromaDB's L2 distance: `relevance = 1.0 / (1.0 + distance)`. A score above ~0.6 is usually "highly relevant"; below ~0.3 is weak.
+
+### Indexed files (what memory_search can find)
+
+The MemoryManager indexes these files only ([agent_core/core/impl/memory/manager.py](agent_core/core/impl/memory/manager.py) `INDEX_TARGET_FILES`):
+
+```
+AGENT.md
+PROACTIVE.md
+MEMORY.md
+USER.md
+EVENT_UNPROCESSED.md
+```
+
+Searches over these are semantic. Files outside this list are NOT in the vector index, even if you `read_file` them often. To find content in non-indexed files, use `grep_files` directly.
+
+### Incremental re-indexing
+
+The watcher at [agent_core/core/impl/memory/memory_file_watcher.py](agent_core/core/impl/memory/memory_file_watcher.py) observes the indexed files. On any change:
+
+```
+1. compute MD5 of changed file
+2. if hash differs from cached hash: remove old chunks, re-chunk, re-index
+3. cache the new hash
+```
+
+Indexing is per-section (split by markdown headers) so one change doesn't re-process the whole file. Logs:
+
+```
+[MemoryFileWatcher] Started watching: <agent_file_system path>
+Memory update complete: {'files_added': N, 'files_updated': N, 'files_removed': N, 'chunks_added': N, 'chunks_removed': N}
+```
+
+### When to use memory_search vs grep vs file read
+
+```
+Question                                         Tool
+──────────────────────────────────────────       ─────────────────────────────
+"What do I know about X?"                        memory_search(query="X")
+"What did the user say about Y last month?"      memory_search(query="user said Y") + read CONVERSATION_HISTORY.md
+"Show me all entries of a specific type"         grep_files "[type]" MEMORY.md
+"What's in USER.md right now?"                   read_file USER.md
+"Find specific text in PROACTIVE.md"             grep_files "<text>" PROACTIVE.md
+"What past tasks involved <subject>?"            grep_files "<subject>" TASK_HISTORY.md
+```
+
+memory_search is for "what do I know about" questions. Grep is for "find this exact string". Pick the right tool.
+
+### Memory pruning
+
+When MEMORY.md exceeds `memory.max_items` in settings.json (default 200), pruning kicks in:
+
+```
+1. memory-processing task includes needs_pruning=True
+2. processor evaluates each entry's relevance and recency
+3. trims down to memory.prune_target (default 135)
+4. discarded entries are dropped (not archived)
+```
+
+Pruning runs at the same time as distillation. Look for `[MEMORY] Process memory task created with pruning phase` in logs.
+
+You can request a manual prune in chat: tell the user, then either wait for next 3am cycle or (if exposed) trigger it. The agent does NOT have a direct "prune now" action.
+
+### Adding a fact you want remembered NOW (between cycles)
+
+memory-processing only runs daily at 3am (or on startup with non-empty buffer). If the user wants something remembered immediately:
+
+```
+Option 1: Add to USER.md
+  For stable user preferences (language, tone, approval rules, etc.)
+  Use stream_edit USER.md → confirm with user → edit takes effect immediately
+  USER.md is in INDEX_TARGET_FILES, so memory_search picks it up.
+
+Option 2: Wait for next pipeline run
+  Every interaction is in EVENT_UNPROCESSED.md. The 3am job will distill it.
+  Tell the user: "I'll remember that — it'll be distilled into long-term
+  memory in the next memory cycle."
+
+Option 3: Manual trigger (if user requests)
+  Some installs expose a way to fire memory_processing on demand
+  (e.g. via a slash command). If not exposed, only the user can trigger.
+  Do NOT fabricate a way.
+```
+
+### Hard rules
+
+- You MUST NOT `stream_edit` or `write_file` MEMORY.md. Only the memory processor writes there.
+- You MUST NOT edit EVENT.md, EVENT_UNPROCESSED.md, CONVERSATION_HISTORY.md, or TASK_HISTORY.md.
+- You MAY edit USER.md (with user confirmation, see `## Self-Edit`).
+- You MAY edit AGENT.md (with caution, see `## Self-Edit`).
+- Calling `grep_files` on MEMORY.md is OK for inspection, BUT for retrieval use `memory_search`. Grep misses semantic matches and skips relevance ranking.
+- The vector index lives in `chroma_db_memory/` — do NOT edit by hand.
+
+### Settings that affect memory
+
+In [app/config/settings.json](app/config/settings.json) `memory` block (see `## Configs`):
+
+```
+memory.enabled            bool. If false, memory_search returns empty + no
+                          pipeline runs. Pipeline trigger is skipped at the
+                          react level (is_memory_enabled() check).
+memory.max_items          int (default 200). Trigger threshold for pruning.
+memory.prune_target       int (default 135). Target size after a prune.
+memory.item_word_limit    int (default 150). Soft cap on words per stored item.
+```
+
+Toggling `memory.enabled` to false does NOT delete `MEMORY.md` or `chroma_db_memory/`. It just stops the pipeline from running and `memory_search` from returning results.
+
+### Pitfalls
+
+- `memory_search` returns "Memory is disabled" → check `memory.enabled` in settings.json. The user may have turned it off.
+- `memory_search` returns empty `results: []` with no error → the index may be empty (fresh install) or the query phrasing doesn't match the indexed content. Try rephrasing or `grep_files` as fallback.
+- Editing AGENT.md, USER.md, PROACTIVE.md, MEMORY.md, or EVENT_UNPROCESSED.md re-triggers re-indexing. If you make rapid edits, the watcher debounces but still consumes some time. Don't loop edit-then-search.
+- `relevance_score` is L2-distance-normalized. Don't compare scores across queries (different queries have different score distributions).
+- The `chroma_db_memory/` directory is an opaque ChromaDB store. Do not try to repair or migrate it. If corrupted, the user must delete the directory and let the manager rebuild on next startup.
+
+---
+
+## Proactive
+
+The proactive system lets you fire tasks on a schedule without a user prompt. Two parallel mechanisms exist: **recurring tasks** (in PROACTIVE.md, fired by the heartbeat) and **scheduled tasks** (in scheduler_config.json, fired by cron). Most user-facing automations belong in PROACTIVE.md.
+
+Code: [app/proactive/manager.py](app/proactive/manager.py) (`ProactiveManager`), [app/proactive/parser.py](app/proactive/parser.py), [app/proactive/types.py](app/proactive/types.py). Authority on rubric and tiers: [agent_file_system/PROACTIVE.md](agent_file_system/PROACTIVE.md).
+
+### Two mechanisms — when to use each
+
+```
+PROACTIVE.md (preferred for user automations)        scheduler_config.json (system + one-offs)
+───────────────────────────────────────────────      ────────────────────────────────────────────
+recurring_add / recurring_read /                     schedule_task / scheduled_task_list /
+recurring_update_task / recurring_remove             schedule_task_toggle / remove_scheduled_task
+
+Frequencies: hourly | daily | weekly | monthly       Schedule expressions: "every day at 3am",
+                                                     cron "0,30 * * * *", "in 2 hours",
+                                                     "tomorrow at 9am", "immediate", etc.
+
+Heartbeat (every 30 min) checks for due tasks        Each entry has its own cron, fires
+across ALL frequencies, runs each that's due,        independently. One-time entries auto-remove.
+respecting time / day filters.
+
+Decision Rubric and Permission Tiers apply.          No rubric or tier system at this level.
+                                                     Scheduled tasks just fire as configured.
+
+Use for: morning briefings, weekly reviews,          Use for: built-in schedules (memory-processing,
+recurring user-facing automations, anything          heartbeat, planners), one-time reminders
+with a permission_tier and conditions.               ("remind me at 3pm tomorrow"), system jobs.
+```
+
+The user wants a daily morning briefing? Use `recurring_add`. The user wants a one-time "remind me at 5pm"? Use `schedule_task`.
+
+### When to set up a proactive task
+
+A proactive task is justified ONLY when ALL of these are true:
+
+```
+1. The user explicitly asked for it, OR you are extending a clear recurring
+   pattern they already use.
+2. The work is repeatable, predictable, and useful enough to justify the
+   cost of running it on schedule.
+3. The output is actionable — has a clear destination (chat, file, integration).
+4. The user has consented to the cadence and the permission tier.
+5. There is no existing recurring task that does the same thing.
+```
+
+Reject the impulse to add proactive tasks aggressively. Each one consumes LLM turns on a schedule and clutters the user's mental model.
+
+DO NOT auto-create a proactive task because it "sounds useful". Always offer first, get explicit consent, then create.
+
+### When NOT to set up a proactive task
+
+```
+- One-off requests ("check the weather right now") → just do it inline.
+- Tasks with vague triggers or unclear stop conditions.
+- Tasks the user might forget they set up. Better to add as a one-time
+  reminder via schedule_task with a fixed end date.
+- Tasks that need real-time event triggers, not time-based ones (e.g. "tell
+  me when X arrives in my inbox" is better solved with an integration
+  listener, not a poll-every-hour proactive task).
+- Tasks that overlap with an existing one. Run recurring_read first.
+```
+
+### Built-in scheduler entries (do NOT remove)
+
+These ship pre-configured in [app/config/scheduler_config.json](app/config/scheduler_config.json) and run the system itself:
+
+```
+id                  schedule              purpose
+─────────────────   ──────────────────    ─────────────────────────────────────────────────
+heartbeat           0,30 * * * *          every 30 min: scan PROACTIVE.md, fire due tasks
+memory-processing   every day at 3am      distill EVENT_UNPROCESSED.md into MEMORY.md (## Memory)
+day-planner         every day at 7am      review yesterday + plan today's proactive priorities
+week-planner        every sunday at 5pm   weekly review, update Goals/Plan/Status in PROACTIVE.md
+month-planner       0 8 1 * *             1st of month 8am, monthly review
+```
+
+Removing or disabling these breaks the system. If the user wants to STOP them firing (e.g., disable proactive entirely), set `proactive.enabled: false` in `settings.json` instead.
+
+### Planners deep-dive
+
+Three time-horizon planners ship as separate skills, each owning one cadence:
+
+```
+day-planner       (skills/day-planner/SKILL.md)        daily 7am
+week-planner      (skills/week-planner/SKILL.md)       Sunday 5pm
+month-planner     (skills/month-planner/SKILL.md)      1st of month 8am
+```
+
+The fourth executor in this family is `heartbeat-processor` — not strictly a planner, but the same family pattern. It fires every 30 min and runs whatever PROACTIVE.md says is due.
+
+All four share an important property: **silent execution**. They override standard task completion rules ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md), [skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md)):
+
+```
+NO acknowledgement to user on task start.
+NO waiting for user confirmation before task_end.
+MUST call task_end immediately after the planning/execution work is done.
+MAY send_message at tier 1 (notify, no wait) when there's something user-facing.
+NEVER block on a user reply (no wait_for_user_reply=true except when proposing a new task).
+```
+
+Why: planners and heartbeat run automatically. If they wait for user confirmation each cycle, tasks pile up indefinitely.
+
+**day-planner** ([skills/day-planner/SKILL.md](skills/day-planner/SKILL.md))
+- Fires daily at 7am via scheduler.
+- Pre-flight reads: `scheduled_task_list`, PROACTIVE.md, TASK_HISTORY.md, MEMORY.md, USER.md, recent CONVERSATION_HISTORY.md.
+- Goal: "How can I help the user get SLIGHTLY closer to their goals TODAY?"
+- Output: updates the Goals / Plan / Status section in PROACTIVE.md with the day's priorities. Optionally proposes ONE new recurring or scheduled task with `wait_for_user_reply=true` and a 20-hour timeout (does NOT add the task if user doesn't reply in 20 hours).
+- Action sets loaded by default: `file_operations`, `proactive`, `scheduler`, `google_calendar`, `notion`, `web`.
+
+**week-planner** ([skills/week-planner/SKILL.md](skills/week-planner/SKILL.md))
+- Fires Sunday 5pm.
+- Reviews the past week's outcomes, updates the weekly section of Goals / Plan / Status, and may propose changes to recurring tasks (frequency tweaks, retiring stale tasks).
+
+**month-planner** ([skills/month-planner/SKILL.md](skills/month-planner/SKILL.md))
+- Fires 1st of month at 8am.
+- Long-horizon: monthly themes, big-picture goal review, retiring or renaming PROACTIVE.md tasks that no longer serve.
+
+**heartbeat-processor** ([skills/heartbeat-processor/SKILL.md](skills/heartbeat-processor/SKILL.md))
+- Fires every 30 min via the `heartbeat` schedule.
+- For each due task in PROACTIVE.md, picks one of two execution types:
+  - **INLINE** (default for tier 0-1, simple actions): runs the task in this heartbeat session, sends optional tier-1 notification, records outcome via `recurring_update_task add_outcome`, moves on.
+  - **SCHEDULED**: spawns a separate session via `schedule_task(schedule="immediate", ...)` when the task needs different action sets, complex multi-step work, or its own session lifecycle.
+- After processing all due tasks, calls `task_end` immediately.
+
+**Custom planners exist.** The repo also ships skills like `compliance-cert-planner` and `task-planner` for narrower cadences. They follow the same silent-execution pattern but are wired in via separate scheduler entries when needed. Read their SKILL.md to learn what they do; don't assume they're active without confirming.
+
+**Reading the planners' output.** The Goals / Plan / Status section of PROACTIVE.md is where planners speak to you. When you start a task, scan that section for current focus and recent accomplishments — that's the cheapest way to align with the user's stated direction.
+
+### One-time / immediate proactive tasks (fire-and-check-back)
+
+The most underused pattern in this section. Use it when:
+
+- The user wants something done at a SPECIFIC future moment (not on a recurring cadence).
+- The user wants something done IMMEDIATELY but in a separate session that returns a result later.
+- You're inside a task and want to spawn a parallel sub-task whose result you'll check on next time you wake up.
+- A planner has identified a concrete one-shot action ("research X tomorrow morning at 9am").
+
+These tasks fire ONCE, return a result via `send_message` and/or by writing to the workspace, and auto-remove themselves from `scheduler_config.json` after firing.
+
+Use `schedule_task` with one of these expressions:
+
+```
+"immediate"              fire NOW (queues an immediate trigger; runs as soon as
+                         the trigger queue picks it up, typically within seconds).
+"in 30 minutes"          fire 30 minutes from now.
+"in 2 hours"             fire 2 hours from now.
+"at 3pm"                 fire at 3pm today (or tomorrow if 3pm has passed).
+"at 3:30pm"              fire at 3:30pm today.
+"at 3:30pm today"        explicit today (rejects if past).
+"tomorrow at 9am"        fire 9am tomorrow.
+```
+
+Schema reminder (full table is in "Scheduled task actions" above):
+
+```
+schedule_task(
+  name="<short name>",
+  instruction="<what to do, in clear imperative voice>",
+  schedule="<expression from list above>",
+  mode="simple" | "complex",         default "simple"
+  priority=<1-100>,                   default 50
+  enabled=True,                       always true for one-shots
+  action_sets=[<sets needed>],        if known; otherwise auto-selected
+  skills=[<skills needed>],           rare for user-driven one-shots
+  payload={...}                       optional extra data for the trigger
+)
+```
+
+**When to set `mode="simple"` vs `mode="complex"` for a one-shot:**
+
+```
+simple    quick lookup, single output (3 actions or fewer). No user-approval gate. Auto-ends.
+complex   multi-step research, document generation, multi-source compile. User approval at end.
+```
+
+Default to simple for one-shots unless the work clearly needs todos.
+
+**Examples.**
+
+User says: "in 30 minutes, remind me to take the laundry out"
+
+```
+schedule_task(
+  name="Laundry reminder",
+  instruction="Send the user a brief reminder to take the laundry out.",
+  schedule="in 30 minutes",
+  mode="simple",
+)
+```
+
+User says: "research the new Apple Vision Pro reviews and give me a summary tomorrow morning at 8am"
+
+```
+schedule_task(
+  name="Apple Vision Pro review summary",
+  instruction=(
+    "Search the web for the latest Apple Vision Pro reviews from credible "
+    "tech publications. Compile a summary covering: hardware impressions, "
+    "software/UX feedback, comparison to competitors, common complaints, "
+    "common praise. Send the summary to the user via send_message."
+  ),
+  schedule="tomorrow at 8am",
+  mode="complex",
+  action_sets=["web_research", "file_operations"],
+)
+```
+
+User asks you (mid-task) to "also start checking the GitHub issue I just opened" while you're doing something else:
+
+```
+schedule_task(
+  name="Monitor GitHub issue #X",
+  instruction="Fetch the GitHub issue at <url> right now and report the latest comments and status.",
+  schedule="immediate",
+  mode="simple",
+  action_sets=["github"],
+)
+```
+
+`schedule="immediate"` queues a trigger that fires within seconds. The agent (in a fresh task) picks it up, runs the instruction, returns. The current task is unaffected.
+
+**Why this pattern matters.** It lets you parallelize: spawn a one-shot, keep working on the main task, and the user gets the spawned task's result asynchronously via send_message. It's also the right pattern when a planner identifies a discrete future action — the planner schedules the task, then ends silently, and the future-agent runs the actual work later.
+
+**One-shot lifecycle.**
+
+```
+1. schedule_task(schedule="<future moment>", ...) creates entry in scheduler_config.json.
+2. The scheduler holds it until fire_at is reached.
+3. At fire_at, scheduler emits a trigger with payload.type="scheduled" (or as configured).
+4. react() routes the trigger to the conversation/simple/complex workflow based on mode.
+5. The agent runs the instruction.
+6. After firing, the scheduler removes the entry (one-shots are auto-removed).
+7. Final result is in EVENT.md, send_message output, or workspace files (depending on instruction).
+```
+
+**Verifying a one-shot is queued:**
+
+```
+scheduled_task_list()                              ← see all entries + next fire times
+read_file app/config/scheduler_config.json         ← raw inspection
+```
+
+If a one-shot was supposed to fire but didn't, check:
+- `proactive.enabled` in settings.json
+- `enabled: true` on the entry
+- The schedule expression parsed correctly (failed parse = entry never created — check for an error in the action's return)
+- The system was running at fire time (CraftBot must be alive for the trigger to fire)
+
+### After a proactive task fires — thinking about what's next
+
+A proactive task that runs and disappears without follow-up wastes the work. After ANY proactive task (recurring or one-time) finishes, the executing agent should consider:
+
+**1. Did the task fully achieve its goal?**
+
+```
+Yes  →  record the outcome with recurring_update_task add_outcome (for recurring)
+        or just log via task_end summary (for one-shots).
+        Move on.
+
+Partially  →  record what was achieved AND what's outstanding.
+              Decide: spawn a follow-up via schedule_task for the remainder?
+              Or surface the gap to the user?
+
+No (failed)  →  record the failure with success=false.
+                Decide: was it transient (retry next cycle), approach-wrong
+                (change instruction or scope), or impossible (disable task,
+                surface to user)?
+                See ## Errors for the failure taxonomy.
+```
+
+**2. Is there a natural follow-up the user would want?**
+
+```
+The task surfaced new information that needs action  →  schedule_task immediate
+                                                         for the action; or send_message
+                                                         to the user with the finding.
+The task identified an emerging pattern              →  consider proposing a NEW recurring
+                                                         task (with user consent) to track it.
+The task confirmed nothing changed                   →  silent task_end; no follow-up needed.
+The task hit a blocker that requires user input      →  send_message with a specific question;
+                                                         do NOT schedule another attempt
+                                                         until the user replies.
+```
+
+**3. Should the recurring task itself be adjusted?**
+
+If the same recurring task has hit the SAME outcome multiple times in a row (visible in `outcome_history`), consider:
+
+```
+- Increase or decrease frequency (e.g., daily → weekly).
+- Tighten or relax conditions (e.g., add weekdays_only).
+- Update the instruction to reflect what actually works.
+- Disable the task if it's no longer useful.
+```
+
+Use `recurring_update_task` with the appropriate `updates` dict. Don't make these changes silently for tasks the user set up — confirm first.
+
+**4. Is the Goals / Plan / Status section in PROACTIVE.md still accurate?**
+
+If a proactive task accomplished or invalidated something in the planner-maintained section:
+
+```
+- Mark a "Plan" item as completed.
+- Update "Status" to reflect new state.
+- Drop a stale "Goal" if the user no longer cares.
+```
+
+Planners (day, week, month) update this section automatically on their cadence, but you can update it sooner when a task produces a clear state change. Use `stream_edit` carefully — preserve the section's structure.
+
+**5. Memory and self-edit.**
+
+If the task surfaced a stable user preference or an enduring fact, that belongs in USER.md or eventually MEMORY.md (via the daily distillation, see `## Memory`). One-time facts in EVENT.md are enough.
+
+If the task revealed an operational lesson useful to future-you, consider whether AGENT.md needs an update (see `## Self-Edit`).
+
+**6. Default behavior at the end of a proactive task:**
+
+```
+1. recurring_update_task add_outcome    (recurring tasks only)
+2. send_message at the right tier        (if there's anything user-facing)
+3. task_end                              (always)
+```
+
+That's the minimum. Steps 1 and 3 are non-optional for recurring tasks.
+
+**Anti-patterns when ending a proactive task:**
+
+- Calling `task_end` without recording an outcome on a recurring task.
+- Sending a message at higher tier than configured (tier 1 task → don't bombard with tier 2 approval requests).
+- Leaving a follow-up implicit ("the user will probably ask"). If you decided a follow-up is needed, schedule it explicitly via `schedule_task`.
+- Re-running the same logic that just failed without changing approach.
+- Loop guard: if `outcome_history` shows N consecutive failures, do NOT keep retrying. Disable the task or surface to the user.
+
+### Heartbeat behavior
+
+Every 30 min (`0,30 * * * *`):
+
+```
+1. fires payload.type="proactive_heartbeat" trigger
+2. _handle_proactive_heartbeat() in app/agent_base.py:
+     proactive_manager.get_all_due_tasks()  → filter by frequency + time + day
+     if no due tasks: return silently
+     if due tasks: create one Heartbeat task with mode=simple,
+                   action_sets=[file_operations, proactive, web_research],
+                   skill=heartbeat-processor
+3. Heartbeat task runs through the heartbeat-processor skill, which executes
+   each due task in turn, respecting permission tiers.
+4. After each task, recurring_update_task records the outcome.
+```
+
+If `proactive.enabled` is false in settings.json, step 1 fires but step 2 returns early. The task is not created.
+
+### Recurring task actions (PROACTIVE.md)
+
+```
+recurring_add(name, frequency, instruction, time?, day?, priority?, permission_tier?, enabled?, conditions?)
+  Adds a new recurring task to PROACTIVE.md.
+  frequency: "hourly" | "daily" | "weekly" | "monthly"   (REQUIRED)
+  time:      "HH:MM" 24-hour                              (recommended for daily/weekly/monthly)
+  day:       "monday".."sunday" for weekly                (for weekly)
+             "1".."31" for monthly                        (for monthly)
+  priority:  1-100, lower = higher priority. Default 50.
+  permission_tier: 0-3. Default 1. See PROACTIVE.md for semantics.
+  enabled:   bool. Default true.
+  conditions: optional list of {type: "..."} filters
+              (e.g. [{type: "market_hours_only"}, {type: "weekdays_only"}])
+  Returns:   { status, task_id, message }
+
+recurring_read(frequency?, enabled_only?)
+  Lists existing recurring tasks. Use to check for duplicates BEFORE adding.
+  frequency:    "all" | "hourly" | "daily" | "weekly" | "monthly"
+  enabled_only: bool, default true
+
+recurring_update_task(task_id, updates?, add_outcome?)
+  Modifies a task or records an execution outcome.
+  updates:     dict with any of: enabled, priority, permission_tier,
+               instruction, time, day, name
+  add_outcome: dict with result (string) and optionally success (bool)
+               USE THIS after every proactive task execution to record
+               result, even if success. The task's outcome_history (capped
+               at the most recent entries) feeds future decisions.
+
+recurring_remove(task_id)
+  Deletes a task entirely. Confirm with user first if removing a task they
+  set up.
+```
+
+### Scheduled task actions (scheduler_config.json)
+
+```
+schedule_task(name, instruction, schedule, priority?, mode?, enabled?,
+              action_sets?, skills?, payload?)
+  Adds a one-time, recurring, or immediate scheduled task.
+  schedule expression formats (validated by app/scheduler/parser.py):
+    "immediate"
+    "at 3pm" / "at 3:30pm" / "at 3:30pm today"
+    "tomorrow at 9am"
+    "in 2 hours" / "in 30 minutes"
+    "every day at 7am" / "every day at 3:30pm"
+    "every monday at 9am"
+    "every 3 hours" / "every 30 minutes"
+    cron: "0 7 * * *"
+  NOT accepted: "daily at", "every weekday", "every morning", freeform text.
+  mode:        "simple" | "complex". Default "simple".
+  payload.type drives workflow routing if set (rare; usually omit).
+
+scheduled_task_list()
+  Lists all scheduled tasks (system schedules + user-added).
+
+schedule_task_toggle(schedule_id, enabled)
+  Enables or disables a schedule without removing it.
+
+remove_scheduled_task(schedule_id)
+  Deletes a schedule. Built-in schedules can be removed but should NOT be.
+```
+
+### Setting up a proactive task — chat-driven flow
+
+User says: "remind me to drink water every 2 hours" or "set up a daily 7am morning briefing".
+
+```
+Step 1: Acknowledge and decide which mechanism
+        - Time-based + recurring + frequency matches PROACTIVE.md → recurring_add
+        - One-off, fixed time, or interval that doesn't fit hourly/daily/weekly/monthly → schedule_task
+        - Hourly with no specific time → recurring_add(frequency="hourly")
+
+Step 2: Check for duplicates
+        recurring_read(frequency="<freq>")           ← for PROACTIVE.md
+        OR scheduled_task_list()                      ← for scheduler_config.json
+        If a similar task exists, confirm with user before adding another.
+
+Step 3: Confirm the details with the user
+        - Exact instruction the agent will follow when fired
+        - Frequency / time / day
+        - Permission tier (see PROACTIVE.md). Default to tier 1 unless user
+          explicitly wants tier 0 (silent) or tier 2+ (approval).
+        - Conditions if any (weekdays only, market hours only, etc.)
+
+Step 4: Create the task
+        recurring_add(...) OR schedule_task(...)
+
+Step 5: Confirm to user
+        State the task ID, frequency, next fire time, and tier.
+        Tell them how to disable: "Run /help recurring or ask me to remove it."
+
+Step 6: When the task fires later (heartbeat-processor skill runs it):
+        - Execute the instruction
+        - Send any user-facing output via send_message (respecting tier)
+        - Call recurring_update_task with add_outcome to record the result
+```
+
+Example exchange:
+
+```
+User: "remind me to take a walk every weekday at 3pm"
+
+Agent (in conversation mode):
+  task_start(task_mode="simple", ...)
+
+Agent (inside task):
+  recurring_read(frequency="daily", enabled_only=true)
+  → no duplicate
+
+  send_message:
+    "I can set that up. Confirming:
+     - Instruction: send a reminder to take a walk
+     - Frequency: daily at 15:00
+     - Days: weekdays only
+     - Permission tier: 1 (notify and proceed without approval)
+     OK to add?"
+
+User: "yes"
+
+Agent:
+  recurring_add(
+    name="Take a walk",
+    frequency="daily",
+    instruction="Send the user a brief, friendly reminder to take a walk.",
+    time="15:00",
+    permission_tier=1,
+    conditions=[{"type": "weekdays_only"}],
+    enabled=true,
+  )
+  → returns { status: "ok", task_id: "take_a_walk_001" }
+
+Agent:
+  send_message:
+    "Done. 'Take a walk' is scheduled weekdays at 3pm. Next run:
+     <next weekday>. Tell me if you want to change it or remove it."
+  task_end
+```
+
+### Permission tiers (high-level — full table in PROACTIVE.md)
+
+```
+tier 0    silent - the task runs but does NOT message the user. Used for
+          background data collection or memory updates.
+tier 1    notify - the task runs and sends a brief notification or result.
+          Default for most user-facing automations.
+tier 2    approval - the task pauses and asks the user before doing the
+          actual work. Used for actions that change state.
+tier 3    high-risk - the task pauses, asks, AND defers to the user for
+          execution. Reserved for irreversible / external-facing actions.
+```
+
+When unsure, default to tier 1. Never set tier 0 without confirming the user actually wants silent execution.
+
+For the FULL Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold >= 18) and the per-tier behavior contract, read [PROACTIVE.md](agent_file_system/PROACTIVE.md). PROACTIVE.md owns those definitions; do NOT duplicate them.
+
+### Conditions (filtering when a task fires)
+
+The `conditions` array on a recurring task lets you filter executions:
+
+```
+{"type": "weekdays_only"}        skip Saturday/Sunday
+{"type": "market_hours_only"}    only during market hours (9:30-16:00 ET)
+{"type": "user_active"}          only when the user has been active recently
+{"type": "<custom>"}             custom predicate evaluated by heartbeat-processor
+```
+
+Read [PROACTIVE.md](agent_file_system/PROACTIVE.md) for the full list of supported conditions.
+
+### Recording outcomes — feedback loop
+
+Every recurring task should record its outcome via `recurring_update_task add_outcome` so future executions can learn from history. The `outcome_history` field on a task keeps the most recent entries (typically last 5-10).
+
+```
+After executing a proactive task, call:
+  recurring_update_task(
+    task_id="<id>",
+    add_outcome={
+      "result": "Sent the morning briefing. Calendar had 3 meetings, top priority was X.",
+      "success": True,
+    }
+  )
+```
+
+This is non-optional. Without outcome history, the task has no memory of what it did before, and decisions about whether to re-fire degrade over time.
+
+### Pitfalls
+
+- Adding a proactive task without user consent. Don't. Always offer first, get explicit yes, then create.
+- Skipping the duplicate check. Always run `recurring_read` before `recurring_add`.
+- Setting `permission_tier=0` (silent) by default. Default to 1 unless the user clearly wants silent.
+- Putting a one-off reminder in PROACTIVE.md (it'll fire forever). Use `schedule_task` for one-offs — they auto-remove.
+- Using freeform schedule expressions in `schedule_task` ("daily at 9am" is rejected; use "every day at 9am").
+- Forgetting to call `recurring_update_task add_outcome` after the task runs. Outcome history powers future decisions.
+- Removing built-in schedules (`heartbeat`, `memory-processing`, `*-planner`). The system depends on them.
+- Editing PROACTIVE.md or scheduler_config.json directly when an action exists. The actions validate inputs; manual edits can break the parser.
+
+### Verifying the schedule is set up
+
+```
+1. recurring_read(frequency="all", enabled_only=false)   ← see all entries
+2. read_file agent_file_system/PROACTIVE.md              ← inspect raw
+3. grep_files "[PROACTIVE]" logs/<latest>.log -A 1       ← startup confirmation
+4. After the next scheduled fire time, check logs and EVENT.md for execution.
+```
+
+If the task should have fired but didn't, check:
+- `proactive.enabled` in settings.json (master switch)
+- `enabled` on the task itself in PROACTIVE.md
+- `time` and `day` match the current moment
+- `conditions` are met
+- The heartbeat itself fired (`grep_files "Heartbeat" logs/<latest>.log`)
+
+### Where authority lives
+
+```
+Decision Rubric (Impact / Risk / Cost / Urgency / Confidence, threshold)   →  PROACTIVE.md
+Permission Tiers (0-3 detailed contract)                                    →  PROACTIVE.md
+Recurring task YAML schema                                                  →  PROACTIVE.md
+Goals / Plan / Status section (planner-maintained)                          →  PROACTIVE.md
+Schedule expression grammar                                                 →  app/scheduler/parser.py
+Heartbeat dispatch logic                                                    →  app/agent_base.py _handle_proactive_heartbeat
+PROACTIVE.md parsing / serialization                                        →  app/proactive/parser.py
+ProactiveManager API                                                        →  app/proactive/manager.py
+```
+
+This file (AGENT.md) is the operations playbook. PROACTIVE.md is the policy and schema spec. Read both when in doubt.
+
+---
+
+## Onboarding Context
+
+First-run state is tracked in [app/config/onboarding_config.json](app/config/onboarding_config.json).
+
+### Two phases
+
+| Phase | What it does | Output |
+|---|---|---|
+| Hard onboarding | Wizard collects user_name, location, language, tone, proactivity, approval rules, messaging_platform | Writes USER.md |
+| Soft onboarding | Conversational interview launched as a task | Refines USER.md, plus learnings |
+
+### Skill
+
+The soft phase uses the `user-profile-interview` skill (see [skills/user-profile-interview/SKILL.md](skills/user-profile-interview/SKILL.md)).
+
+### Templates
+
+On first run, templates from [app/data/agent_file_system_template/](app/data/agent_file_system_template/) seed `agent_file_system/` (AGENT.md, USER.md, SOUL.md, FORMAT.md, PROACTIVE.md, etc.).
+
+### Your behavior during onboarding
+
+- If `hard_completed` is false, prefer asking the user for missing profile details over assuming.
+- If `soft_completed` is false, the soft interview is pending — be open to expanding USER.md based on user input.
+- Do NOT edit `onboarding_config.json` directly — the onboarding flow manages it.
+
+---
+
+## Self-Improvement
+
+You are a self-improving agent. The harness exposes a set of mutable surfaces — config files, skill directories, action registry, memory, your own operational manual — and you have actions to modify each. Self-improvement is the deliberate use of those mutations to close capability gaps, encode learned workflows, and make future-you better at the user's tasks.
+
+There are two modes:
+
+```
+ON-DEMAND   Triggered by a user request, a capability gap, or a recognized
+            pattern mid-task. Targeted and immediate. The agent installs
+            an MCP, edits a config, or updates AGENT.md.
+
+OVER TIME   Passive. The memory pipeline distills patterns, planners review
+            and adjust PROACTIVE.md, and the agent self-edits AGENT.md when
+            a pattern recurs across many tasks. The user does not see most
+            of this; it accumulates.
+```
+
+Both modes use the same underlying mechanisms. The difference is who triggers them and how visible the change is.
+
+### What you can improve, and where the change lives
+
+```
+What                                  Where it lives                                Section
+────────────────────────────────────  ────────────────────────────────────────      ─────────────
+Tools (external services)              MCP servers in mcp_config.json                ## MCP
+Workflows (composed sequences)         Skills in skills/<name>/SKILL.md              ## Skills
+Action surface (agent-side code)       New action .py in app/data/action/            ## Actions
+External service connections           credentials via connect_integration            ## Integrations
+LLM brain                              model.* in settings.json + /provider          ## Models
+API keys                               api_keys.* in settings.json                   ## Models / ## Configs
+Recurring automations                  PROACTIVE.md via recurring_add                ## Proactive
+One-off scheduled work                 schedule_task action                          ## Proactive
+Memory recall behavior                 memory.* in settings.json + USER.md           ## Memory / ## Self-Edit
+Operational manual (this file)         AGENT.md                                      ## Self-Edit
+User preferences                       USER.md                                       ## Self-Edit
+Personality / tone                     SOUL.md                                       ## Self-Edit
+Document formatting standards          FORMAT.md                                     ## Documents
+Living UI global design                GLOBAL_LIVING_UI.md                           ## Living UI
+Hot-reload behavior                    config files (auto-applies)                   ## Configs
+```
+
+For any improvement, the right question is: which surface should change? If you can't pick one, the improvement isn't well-defined yet — talk to the user before acting.
+
+### Triggers — when to consider self-improvement
+
+```
+Trigger                                                         Improvement type
+────────────────────────────────────────────────────────────     ──────────────────────────────────────
+User explicit ask: "add an MCP for X" / "always do Y"             on-demand: install / update
+A required action is unavailable (capability gap)                  on-demand: MCP / new action / integration
+You hit the same workaround 3+ times across tasks                  over time: AGENT.md update or new skill
+Repeated user complaint of the same kind                           on-demand: USER.md or AGENT.md update
+A new environment fact (file gained a new section, integration    on-demand: AGENT.md
+  added a new endpoint, settings.json got a new key)
+Day/week/month planner identifies a candidate proactive task       on-demand: recurring_add (with consent)
+Memory distillation surfaces a stable preference                   over time: USER.md (planners can do this)
+LLMConsecutiveFailureError                                          on-demand: model/key fix (## Models)
+Action returns "Not connected" repeatedly                          on-demand: walk user through integration
+PROACTIVE.md task hits same outcome N times in a row               on-demand: recurring_update_task (tweak)
+```
+
+If none of these triggers fired, do NOT self-improve. Random tweaks bloat configs and confuse the user.
+
+### The improvement loop
+
+Replace the simple IDENTIFY/SEARCH/INSTALL/WAIT/CONTINUE/REMEMBER with this fuller cycle:
+
+```
+1. RECOGNIZE
+   - You see a gap, friction, or explicit user ask.
+   - Name it precisely. "I cannot send messages to Slack" is precise.
+     "I should be more helpful" is not.
+
+2. CATEGORIZE
+   - Which improvement surface? (See the table above.)
+   - If multiple surfaces could serve, pick the lightest:
+     - Skill < Action < MCP < Integration in install cost.
+     - USER.md / SOUL.md < AGENT.md in self-edit risk.
+
+3. VALIDATE
+   - Is this worth doing? Will the change be used more than once?
+   - Will it hurt anything else? (e.g., a new MCP server adds tokens
+     to every prompt that loads its action set; do not add cavalierly.)
+   - Is there an existing surface that already covers this and you
+     just missed it? Run discovery actions before authoring (## Actions,
+     ## Skills, ## MCP discovery sections).
+
+4. PROPOSE
+   - Tell the user what you want to change and why, in one or two
+     sentences. Get explicit consent for anything that:
+     - Edits config files
+     - Installs new code (git clone, pip install)
+     - Asks for credentials
+     - Modifies AGENT.md or SOUL.md
+   - For trivial in-task tweaks (e.g., adding a single recurring task
+     after the user asked for it) the propose step IS the request
+     itself. Do not over-confirm.
+
+5. EXECUTE
+   - Use the right action / config edit (see per-category recipes below).
+   - One change at a time. Do not bundle a config edit with an AGENT.md
+     update with a new skill in one go — each step needs verification.
+
+6. VERIFY
+   - Run a smoke test. For each surface:
+     - MCP: list_action_sets and call one tool.
+     - Skill: /skill list and (if simple) invoke the skill.
+     - Integration: check_integration_status.
+     - Model: send_message and watch for LLMConsecutiveFailureError.
+     - PROACTIVE.md: recurring_read.
+     - AGENT.md self-edit: re-read the changed section in next turn.
+   - If smoke test fails, ROLLBACK before continuing.
+
+7. CONTINUE
+   - Resume the original task using the new capability. Do not start
+     fresh tasks unless the original task ended (e.g., LLM circuit
+     breaker fired and cancelled it).
+
+8. RECORD
+   - For recurring task outcomes: recurring_update_task add_outcome.
+   - For AGENT.md self-edits: bump version: in front matter and sync
+     to template (see ## Self-Edit).
+   - For everything else: the memory pipeline distills relevant events
+     overnight (see ## Memory). You do NOT need to manually log.
+```
+
+### Per-category recipes (cross-references)
+
+For full step-by-step recipes per surface, follow these pointers. Do not duplicate them here.
+
+```
+Add an MCP server                       →  ## MCP "Add or enable a server (recipe)"
+Author / install a skill                →  ## Skills "Adding a new skill"
+Author a new action                      →  ## Actions "Authoring a new action"
+                                            Note: requires RESTART (no hot-reload for code).
+Connect an integration                   →  ## Integrations "End-to-end chat-driven connection"
+Switch model / set API key               →  ## Models "Switching provider or model"
+Add a recurring task                     →  ## Proactive "Setting up a proactive task — chat-driven flow"
+Schedule a one-shot                       →  ## Proactive "One-time / immediate proactive tasks"
+Edit FORMAT.md                            →  ## Documents
+Edit GLOBAL_LIVING_UI.md                  →  ## Living UI
+Edit AGENT.md / USER.md / SOUL.md         →  ## Self-Edit
+Adjust memory settings                    →  ## Memory "Settings that affect memory" + ## Configs
+Adjust scheduler entries                  →  ## Configs (## scheduler_config.json schema)
+```
+
+### On-demand self-improvement examples
+
+**Example 1: User asks for a missing capability**
+```
+User: "I want you to be able to manage my Linear issues."
+
+Agent:
+  1. RECOGNIZE: No built-in Linear integration. No connected Linear via MCP.
+  2. CATEGORIZE: External service → MCP server.
+  3. VALIDATE: read mcp_config.json → check for an existing linear-mcp entry.
+     Found: "linear-mcp" exists with enabled: false.
+  4. PROPOSE: send_message: "Linear support exists as an MCP server already
+     in your config but is disabled. To enable, I need a Linear API token.
+     Get one at linear.app/settings/api → Personal API keys. Paste it here."
+  5. EXECUTE: stream_edit mcp_config.json
+       linear-mcp.env.LINEAR_API_TOKEN: "" → "<token>"
+       linear-mcp.enabled: false → true
+  6. VERIFY: wait 0.5s + grep_files "[MCP] Successfully connected to 'linear-mcp'"
+     Then: list_action_sets → confirm "mcp_linear-mcp" appears.
+     Then: add_action_sets("mcp_linear-mcp"); call a Linear tool with a
+     simple read.
+  7. CONTINUE: now do what the user originally wanted ("show me my open issues").
+  8. RECORD: nothing to do; memory pipeline picks up the event.
+```
+
+**Example 2: Mid-task capability gap**
+```
+Mid-task, you need to call a Stripe API. No Stripe integration is connected.
+
+Agent (mid-task, simple flow):
+  1. RECOGNIZE: action attempt failed; "stripe-mcp" exists but is disabled.
+  2. CATEGORIZE: MCP enable.
+  3. VALIDATE: Yes, user is asking about Stripe.
+  4. PROPOSE: send_message: "I need a Stripe API key to do this. Should I
+     enable the Stripe MCP server? You'll need to provide a Stripe secret
+     key (Test mode is fine for non-production)."
+  5. WAIT for user reply with the key. Then enable.
+  6. VERIFY + CONTINUE.
+```
+
+**Example 3: User shares a stable preference**
+```
+User: "always use a serif font in my reports going forward."
+
+Agent:
+  1. RECOGNIZE: durable formatting preference.
+  2. CATEGORIZE: FORMAT.md edit (per-doctype or global).
+  3. VALIDATE: Is this a real preference or one-off? "going forward" makes it durable.
+  4. PROPOSE: implicit (the user already asked); just confirm the scope:
+     send_message: "Got it. I'll add 'serif font' to FORMAT.md as a global
+     rule, applying to all generated docs. Confirm?"
+  5. EXECUTE: stream_edit FORMAT.md ## global section, add rule.
+  6. VERIFY: re-read the section to confirm landed correctly.
+  7. CONTINUE / RECORD as appropriate.
+```
+
+**Example 4: Repeated friction recognized over many tasks**
+```
+You've noticed across 5+ tasks that whenever you generate a PDF, you keep
+forgetting to call create_pdf vs trying to render via run_python first.
+
+Agent (when starting an unrelated PDF task and noticing the pattern):
+  1. RECOGNIZE: pattern of forgetting the right action.
+  2. CATEGORIZE: AGENT.md operational improvement (## Self-Edit).
+     This is a NON-OBVIOUS convention worth recording.
+  3. VALIDATE: yes, future-you would benefit.
+  4. PROPOSE: not always required for AGENT.md polish — but if the user
+     has a pattern of complaining about PDFs, ask. Otherwise, log it.
+  5. EXECUTE: stream_edit AGENT.md ## Documents adding a clarifying note.
+  6. VERIFY: re-read on next turn so the new instruction is in context.
+  7. RECORD: bump version in front matter; sync to template.
+```
+
+### Over-time self-improvement (passive)
+
+You don't drive this directly each turn, but it is happening:
+
+```
+Daily 3am          memory pipeline distills important events into MEMORY.md.
+                   Stable preferences, capabilities, system limits, user
+                   complaints — all surface here for future memory_search.
+
+Daily 7am          day-planner reviews context, may propose a recurring task.
+                   Updates Goals/Plan/Status section in PROACTIVE.md.
+
+Sunday 5pm         week-planner reviews the week's outcomes; may retire stale
+                   recurring tasks or adjust their frequency.
+
+1st of month 8am   month-planner reviews long-horizon goals; broader pruning.
+
+Heartbeat (30 min) executes due recurring tasks; records outcome via
+                   recurring_update_task add_outcome. Repeated failures in
+                   outcome_history feed future planner decisions.
+```
+
+You do NOT need to mimic this work in the foreground. When you complete a task, do step 8 RECORD properly and the over-time machinery picks it up.
+
+### Discovery before installation
+
+Before installing a new capability, run discovery to avoid duplicates:
+
+```
+Need a tool                  →  read_file app/config/mcp_config.json (server may exist disabled)
+                                 list_action_sets (mcp_<name> may already be loaded)
+Need a workflow              →  read_file app/config/skills_config.json (skill may exist disabled)
+                                 list_skills (live state)
+Need an integration          →  list_available_integrations (registry + connected state)
+                                 /cred status (user-side overview)
+Need a recurring task        →  recurring_read (avoid duplicate setups)
+Need a model                 →  read_file settings.json (user may have it set already)
+                                 list of supported providers in ## Models
+```
+
+The most common self-improvement mistake is adding a new entry when an existing one would have worked. Always check first.
+
+### Permission and consent rules
+
+ASK the user before:
+- Editing AGENT.md or SOUL.md (they affect every future interaction).
+- Installing anything that runs new code (git clone, pip install, npx fetch).
+- Adding or modifying anything that needs credentials.
+- Adding a recurring task (## Proactive — explicit consent rule).
+- Switching the LLM provider (it affects cost and behavior).
+- Connecting an integration.
+
+DO NOT need to ask for:
+- Updating USER.md after the user shared a clear durable preference (one-line
+  confirmation is enough: "I'll add that to USER.md").
+- Recording the outcome of a proactive task you just executed.
+- Re-reading a config file or running discovery actions.
+- Editing FORMAT.md after the user gave a one-shot formatting rule (still
+  confirm scope: "global vs file-type-specific").
+
+### Verification and rollback
+
+Every install / edit needs a smoke test. If the smoke test fails:
+
+```
+1. Revert the edit (stream_edit back, OR /mcp disable, OR /skill disable, OR
+   delete a too-broken file).
+2. Tell the user what broke and what you reverted.
+3. Do NOT try the same thing again with no changes (loop trap).
+4. Either propose a different approach or stop and ask the user.
+```
+
+If you can't tell what broke (smoke test is ambiguous): grep the latest log
+for the relevant subsystem tag. See ## Errors "Self-troubleshooting via logs"
+for the workflow.
+
+### Loop guards (mandatory)
+
+```
+- Two consecutive failed installs of the SAME capability   →  STOP. Ask the user.
+- Three consecutive failed smoke tests after edits         →  STOP. Roll back to last known good.
+                                                              Ask the user.
+- A recurring task with N consecutive failure outcomes      →  do NOT keep re-firing.
+  in outcome_history                                          recurring_update_task
+                                                              with enabled=false, then ask.
+- Any AGENT.md edit that broke a previously-working flow    →  revert immediately.
+                                                              version: bump exists for a reason
+                                                              — it's the rollback marker.
+```
+
+### Anti-patterns
+
+- Cavalier installs ("might be useful"). Every MCP server / skill / integration is a tax on prompt size and a maintenance burden. Only install when there is a concrete need.
+- Bundling improvements without verification. One change at a time, smoke test after each.
+- Self-editing AGENT.md mid-task that has nothing to do with self-improvement. AGENT.md edits belong in dedicated improvement tasks (ideally with explicit user consent), not as side effects of arbitrary work.
+- Editing SOUL.md without user consent. Personality changes apply to every interaction; never an automatic move.
+- Treating memory pipeline as a substitute for explicit self-edits. Memory captures EVENTS, not lessons. If you learned a lesson, encode it in AGENT.md so future-you sees it deterministically.
+- Skipping discovery and adding a duplicate (e.g., a second MCP server doing what an existing-but-disabled one already does).
+- Using the wrong surface (e.g., putting a one-time reminder in PROACTIVE.md, putting a system-wide formatting rule in USER.md, putting agent-personality changes in AGENT.md instead of SOUL.md).
+- Setting `permission_tier=0` (silent) on proactive tasks the user didn't explicitly ask to be silent.
+- Improving prematurely. The first time something feels rough, just push through. By the third time, propose an improvement.
+
+### A note on the goal
+
+Self-improvement is not "add capabilities". It's "be measurably more useful to THIS user, on THEIR tasks, with the smallest necessary change". The best self-improvement is often a single line added to USER.md or a stale recurring task disabled — not a new MCP server.
+
+When in doubt, do less.
+
+---
+
+## Self-Edit
+
+Three files in your own file system are agent-editable: `AGENT.md`, `USER.md`, `SOUL.md`. Each affects a different surface, has different consent rules, and a different edit procedure. Picking the wrong file is the #1 self-edit mistake.
+
+This section is the operating manual for those edits. The decision of WHEN to make a self-edit lives in `## Self-Improvement`. This section answers HOW.
+
+### Quick decision: which file to edit
+
+```
+Type of change                                          File              Consent rule
+──────────────────────────────────────────────────────  ────────────────  ──────────────────────────────
+Operational rule about HOW the agent works              AGENT.md          ask before edit
+  (workflows, conventions, schemas, recipes,
+   non-obvious gotchas)
+
+User profile fact (identity, language, time zone,       USER.md           one-line confirm
+  preferred channel, approval rules, life goals)         
+
+Personality / tone / behavior style                     SOUL.md           explicit user request only;
+  (how the agent talks, sense of humor, formality,                         ALWAYS quote back and confirm
+   emoji use, brevity vs verbosity)
+
+Document / file generation standards                    FORMAT.md         confirm scope (global vs
+  (colors, fonts, layouts per file type)                                   per-doctype)
+
+Living UI design rules                                  GLOBAL_LIVING_UI  ask if non-trivial
+  (palette, components, responsive rules)               .md
+
+Per-mission state, multi-task continuity                workspace/        no consent needed
+                                                        missions/<n>/     (it's mission-internal)
+                                                        INDEX.md
+
+Recurring or scheduled task definitions                 PROACTIVE.md      via recurring_* / schedule_*
+                                                        (or scheduler_    actions, NOT manual edit
+                                                        config.json)
+
+A one-off fact you want recalled later                  (do nothing)      memory pipeline picks it up
+                                                                          from EVENT_UNPROCESSED.md
+```
+
+If you can't pick one cleanly, the change isn't well-scoped yet. Ask the user before editing anything.
+
+### AGENT.md (this file)
+
+**Purpose.** Operational manual. Stable rules, schemas, recipes, gotchas. Read by future-you on every relevant task.
+
+**When to edit:**
+- The user explicitly asks for an operational improvement: "from now on, always X", "add a new rule about Y", "update the manual to say Z".
+- You discover a non-obvious convention through repeated experience that future-you would benefit from. Examples:
+  - A config file gained a new section after the user installed something.
+  - A workflow has a gotcha that costs a turn to rediscover each time.
+  - An action has a non-obvious parameter that the LLM keeps missing.
+
+**When NOT to edit:**
+- During a task that isn't about self-improvement. Side-quest edits get lost in unrelated tasks and bloat the manual.
+- To record one-off facts about the current user. Those go in USER.md.
+- To record project-specific findings. Those go in `workspace/missions/<name>/INDEX.md`.
+- To document something the user might change tomorrow. Stable rules only.
+- After your first encounter with a friction. Wait for the second or third. Premature additions are noise.
+
+**Edit procedure:**
+```
+1. Read the section you want to change (and its neighbors) so your edit
+   matches the surrounding tone and structure.
+2. stream_edit AGENT.md (NEVER write_file; you'd lose the rest of the file).
+3. Bump the `version:` line in the front matter when the change is material.
+4. Sync to template: also stream_edit app/data/agent_file_system_template/AGENT.md
+   so new installs get the upgrade. Both files must stay byte-identical.
+5. Re-read the changed section in your next turn so the new content lands
+   in your in-context manual.
+6. For high-impact edits, send_message to the user describing what changed
+   and where (so they can review).
+```
+
+**Style rules** (from observed errors in past edits — see `## Errors`):
+- Optimize for grep. Stable `## <Topic>` headers, HTML markers `<!-- name -->` ... `<!-- /name -->` around schemas and command blocks.
+- No ASCII art, no decorative tables for non-tabular content, no em-dash flourishes, no marketing prose.
+- Topic-anchored cross-references (`see ## Configs`), never `§N` numbers.
+- One change at a time. Don't bundle a structural reorganization with content additions.
+
+**Hard rules:**
+- Never delete a section without user consent.
+- Never demote a section header without user consent (changes grep targets).
+- Never edit AGENT.md on behalf of the agent's preferences. AGENT.md describes the harness, not what the agent personally wants.
+
+### USER.md
+
+**Purpose.** User profile. Identity, communication preferences, agent-interaction rules, life goals, personality. Indexed by `memory_search` (see `## Memory`).
+
+**Standard sections** (do NOT rename):
+```
+## Identity
+   Full Name, Preferred Name, Email, Location, Timezone, Job, etc.
+
+## Communication Preferences
+   Language, Preferred Tone, Response Style, Preferred Messaging Platform.
+
+## Agent Interaction
+   Prefer Proactive Assistance, Approval Required For, working hours, etc.
+
+## Life Goals
+   Long-term goals worth aligning to.
+
+## Personality
+   The user's personality traits the agent should adapt to.
+```
+
+**When to edit:**
+- The user shares a stable preference: "I'm in Tokyo timezone now", "I prefer terse replies", "always confirm before sending email".
+- The onboarding interview produces a fact (handled by the soft-onboarding flow, but you may add to it later).
+- A preference becomes clear from repeated user feedback (3+ instances of the same correction).
+
+**Edit procedure:**
+```
+1. Confirm the preference is durable, not one-off.
+   Quick check: "Want me to remember that for future tasks too?"
+   If yes → durable, edit USER.md.
+   If no → don't edit; let the memory pipeline catch it as a one-off.
+2. stream_edit USER.md.
+3. Write to the RIGHT section (Identity / Communication / Agent Interaction
+   / Life Goals / Personality). If it doesn't fit any, ask the user where
+   they want it.
+4. After saving, send_message confirming the exact line you wrote so the
+   user can correct it.
+```
+
+**Hard rules:**
+- ONE-LINE CONFIRM is the default. Don't over-confirm; the user already told you the preference.
+- Never silently change USER.md. The user must see the diff or your description.
+- Don't put project-specific details here. Those go in `workspace/missions/<name>/INDEX.md`.
+- Don't put SECRETS here (passwords, tokens, credentials). USER.md is indexed by memory_search and surfaces in many contexts.
+- Don't put one-off facts here. "I'm working on X today" is one-off. "I always work on X-class problems" is durable.
+
+### SOUL.md
+
+**Purpose.** Personality, tone, voice, behavior style. **Injected directly into the system prompt every turn.** This is not a reference file — it shapes every word the agent produces.
+
+**When to edit:**
+- ONLY when the user explicitly asks for a personality change: "be more formal", "stop being so cheerful", "use more emojis", "be more concise".
+
+**When NOT to edit:**
+- ANY OTHER REASON. SOUL.md is the highest-stakes file. A wrong edit changes the agent's voice for every future interaction.
+- Inferring a personality preference from indirect signals. If the user complained about tone, ASK what they want changed before editing.
+- "Improving" the soul because you think it could be better. The user owns their agent's personality.
+
+**Edit procedure:**
+```
+1. Read the current SOUL.md fully. Understand the existing voice.
+2. Quote back the exact change you propose to make:
+     "I'll change <quote of current line> to <quote of new line>. Confirm?"
+3. WAIT for the user's reply. Do NOT edit on assumption.
+4. Once confirmed: stream_edit SOUL.md.
+5. Send a short follow-up: "Done. The new voice will start in your next
+   message." (Reminds the user that the change applies immediately.)
+```
+
+**Hard rules:**
+- Always quote-back-and-confirm. No exceptions.
+- Never ADD a new section without the user explicitly asking for one.
+- Never DELETE a section without explicit confirmation.
+- Don't put operational rules here. Operational rules go in AGENT.md. SOUL.md is voice and behavior style only.
+- If the user says "stop doing X" repeatedly and X feels personality-driven, ASK before editing SOUL.md. They might just want a one-task fix, not a permanent voice change.
+
+### FORMAT.md and GLOBAL_LIVING_UI.md
+
+These are not strictly "self" files (they're for output design, not agent behavior), but the agent edits them under similar discipline. See `## Documents` and `## Living UI` for the per-file procedures.
+
+Quick rules:
+- FORMAT.md: edit when the user gives a durable formatting preference. Confirm scope (global vs file-type-specific) before writing.
+- GLOBAL_LIVING_UI.md: edit when the user supplies a new universal UI rule. For project-specific overrides, edit the per-project `LIVING_UI.md` instead.
+
+### AGENT.md ↔ template sync
+
+`agent_file_system/AGENT.md` is the LIVE file the running agent reads.
+`app/data/agent_file_system_template/AGENT.md` is the TEMPLATE that seeds new installs (see `## Onboarding Context`).
+
+```
+When you edit AGENT.md for a durable improvement, the live file and the
+template MUST stay byte-identical:
+
+1. Make the edit on whichever file you started with.
+2. Copy the change to the other file (read the section, stream_edit the same
+   change in the other file).
+3. Verify with: diff agent_file_system/AGENT.md app/data/agent_file_system_template/AGENT.md
+   (or just grep both for the new content; should appear in both).
+```
+
+If a sync drift exists (template diverges from live), the next install for a new user will ship the OLD content. That's a silent failure mode worth fixing immediately.
+
+### Verifying a self-edit
+
+After ANY edit:
+
+```
+For AGENT.md:
+  1. re-read the changed section in your next turn (it's now in your context).
+  2. confirm the front-matter version: bumped (if material change).
+  3. confirm the template was synced.
+
+For USER.md:
+  1. read the section back, paste the relevant lines to the user as
+     confirmation: "I added: <new lines>. Look right?"
+  2. memory_search will pick it up on next index pass (see ## Memory).
+
+For SOUL.md:
+  1. send a short message; the new voice should be visible in YOUR own
+     wording.
+  2. if the user immediately says "that's not what I wanted",
+     ROLL BACK to the previous SOUL.md content (you should have read it
+     before editing — keep the previous version mentally for one turn).
+```
+
+### Rollback procedure
+
+If a self-edit broke something or the user objects:
+
+```
+1. AGENT.md: stream_edit back to the previous content. Bump version: again
+   (every change deserves a version bump, even reversions).
+2. USER.md: stream_edit the offending lines back to old or remove.
+3. SOUL.md: stream_edit back. Apologize briefly. Don't re-edit until the
+   user is explicit about what they want.
+```
+
+If you don't remember the previous content (e.g., it's been many turns), grep TASK_HISTORY.md or EVENT.md for the change event and reconstruct, OR ask the user to describe what they want restored.
+
+### What ENT.md, USER.md, and SOUL.md are NOT
+
+```
+- A scratch pad. Use workspace/tmp/{task_id}/ for that.
+- A todo list. Use task_update_todos.
+- A mission record. Use workspace/missions/<name>/INDEX.md.
+- A diary. Use EVENT.md (the system writes it; you don't).
+- A memory store. Use the memory pipeline + memory_search.
+- A knowledge base for arbitrary user data. Anything that isn't profile,
+  tone, or operational rule does not belong in these files.
+```
+
+### Anti-patterns
+
+- Editing AGENT.md for things that aren't operational rules (project state, one-off opinions, user-specific facts).
+- Editing USER.md for things that aren't user profile (mission state, one-off requests).
+- Editing SOUL.md without quote-back-and-confirm.
+- Forgetting the AGENT.md template sync. The template should never drift.
+- Adding a new section to USER.md without user consent. Stick to the standard sections.
+- Putting credentials, tokens, or secrets in any of these files. They are indexed by memory and visible in chat / logs.
+- Multiple self-edits in one turn without verification between each.
+- Editing AGENT.md silently as part of an unrelated task. Self-edits deserve their own task.
+
+### One-line summary for each file
+
+```
+AGENT.md   "How the harness works, and how to operate within it." (this file)
+USER.md    "Who the user is and what they prefer."
+SOUL.md    "How the agent sounds and behaves."
+```
+
+If a proposed edit doesn't fit cleanly into one of those three sentences, it probably belongs somewhere else.
+
+---
+
+## Glossary
+
+Quick lookup of the terms used throughout this manual. Each entry points to the section that owns the full definition. Grep this section first when an unfamiliar term shows up.
+
+```
+action                    atomic unit the LLM picks each turn                              ## Actions
+action set                named bundle of actions loaded together at task_start            ## Action Sets
+add_action_sets           action that loads additional action sets mid-task                ## Action Sets
+add_outcome               recurring_update_task field for recording execution result       ## Proactive
+agent file system         the persistent agent_file_system/ directory                      ## File System
+AGENT.md                  this file - operational manual                                    ## Self-Edit
+api_keys                  settings.json block holding provider API keys                    ## Configs / ## Models
+auth_type                 integration auth flow shape: oauth/token/both/interactive/...    ## Integrations
+ChromaDB                  vector store under chroma_db_memory/ powering memory_search      ## Memory
+complex task              multi-step task with todos + user-approval gate                  ## Tasks
+ConfigWatcher             0.5s-debounced file watcher for app/config/ files                ## Configs
+connect_integration       action that connects an external service via credentials         ## Integrations
+CONVERSATION_HISTORY.md   rolling dialogue record (do not edit)                            ## File System
+conversation mode         workflow when no task is active; only task_start/send/ignore    ## Tasks / ## Runtime
+core (action set)         always-loaded set; cannot be opted out                            ## Action Sets
+Decision Rubric           proactive task scoring (Impact/Risk/Cost/Urgency/Confidence)     PROACTIVE.md, ## Proactive
+EVENT.md                  complete chronological event log (do not edit)                   ## File System
+EVENT_UNPROCESSED.md      memory pipeline staging buffer (do not edit)                     ## File System / ## Memory
+event pipeline            flow from event -> EVENT_UNPROCESSED -> MEMORY.md                ## Memory
+FORMAT.md                 document/design standards file                                   ## Documents
+GLOBAL_LIVING_UI.md       global Living UI design rules                                    ## Living UI
+heartbeat                 scheduler entry firing every 30 min to run due proactive tasks   ## Proactive
+heartbeat-processor       skill that executes due tasks during a heartbeat                 ## Proactive
+hot-reload                config-watcher debounced 0.5s reload of /app/config/             ## Configs
+INDEX_TARGET_FILES        five files indexed by memory_search                              ## Memory
+integration               external-service connection (Slack, GitHub, Jira, ...)           ## Integrations
+INTEGRATION_HANDLERS      registry of available integration handlers                       ## Integrations
+LIVING_UI.md              per-project doc inside a Living UI project                       ## Living UI / ## File System
+Living UI                 generated React/HTML projects with persistent state              ## Living UI
+LLM                       large language model used for text generation                    ## Models
+LLMConsecutiveFailureError  circuit-breaker after 5 consecutive LLM failures               ## Errors / ## Models
+MCP                       Model Context Protocol; external tool servers                    ## MCP
+mcp_<server_name>         action set name registered when an MCP server connects           ## MCP / ## Action Sets
+memory_search             RAG action over indexed agent_file_system/ files                 ## Memory
+MemoryManager             ChromaDB-backed singleton for memory indexing + retrieval        ## Memory
+MEMORY.md                 distilled long-term memory; read via memory_search only          ## Memory / ## File System
+MISSION_INDEX_TEMPLATE.md template for workspace/missions/<name>/INDEX.md                  ## File System / ## Workspace
+mission                   multi-task initiative in workspace/missions/                     ## Workspace
+MODEL_REGISTRY            agent_core registry mapping providers to default models          ## Models
+onboarding                first-run setup flow (hard wizard + soft interview)              ## Onboarding Context
+outcome_history           per-task list of recent execution outcomes in PROACTIVE.md       ## Proactive
+parallelizable            decorator flag controlling whether action can run in parallel    ## Actions
+permission_tier           0-3 user-interaction level for proactive tasks                   PROACTIVE.md, ## Proactive
+PROACTIVE.md              recurring task definitions + Goals/Plan/Status                   ## Proactive / ## File System
+proactive task            task fired by a schedule, not a user prompt                      ## Proactive
+provider                  LLM provider name (openai, anthropic, gemini, ...)                ## Models
+react()                   the agent's main loop entry point                                 ## Runtime
+recurring_add             action to register a new recurring task in PROACTIVE.md          ## Proactive
+recurring_update_task     action to modify a task or record an outcome                     ## Proactive
+reinitialize_llm          internal call that rebuilds LLMInterface for a provider switch   ## Models
+schedule_task             action to add immediate / one-shot / recurring scheduled task    ## Proactive
+scheduler_config.json     cron schedules for system + user one-shot tasks                  ## Configs / ## Proactive
+simple task               <=3-action auto-ending task with no approval gate                 ## Tasks
+SKILL.md                  skill definition file with YAML frontmatter + body               ## Skills
+slow_mode                 settings.json flag throttling LLM requests                        ## Models
+SOUL.md                   personality file injected directly into system prompt            ## Self-Edit
+stream_edit               preferred action for editing existing files                      ## Files
+task_id                   unique identifier for a task; equals session_id                  ## Tasks / ## Runtime
+task_start                action to begin a task from conversation mode                    ## Tasks
+TASK_HISTORY.md           summaries of completed tasks (do not edit)                       ## File System
+task mode                 simple | complex; locked at task_start                            ## Tasks
+todo phase                Acknowledge / Collect / Execute / Verify / Confirm / Cleanup     ## Tasks
+trigger                   dispatch unit consumed by react()                                 ## Runtime
+USER.md                   user profile file (preferences, identity, goals)                  ## Self-Edit / ## File System
+VLM                       vision-language model used for image actions                      ## Models
+waiting_for_user_reply    task flag; trigger re-queues with 3-hour delay if no reply       ## Runtime / ## Tasks
+workflow                  one of 5 paths react() routes to                                  ## Runtime
+workflow lock             prevents concurrent memory / proactive runs                      ## Runtime
+workspace/                per-agent sandbox under agent_file_system/                        ## Workspace
+```
 
+If a term is missing, search the relevant section header (`grep_files "## <topic>" agent_file_system/AGENT.md`). If you encounter a new term that should be in this glossary, add it via the `## Self-Edit` AGENT.md flow.
diff --git a/app/external_comms/__init__.py b/app/external_comms/__init__.py
deleted file mode 100644
index 33062696..00000000
--- a/app/external_comms/__init__.py
+++ /dev/null
@@ -1,61 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms
-
-External communication channels for CraftBot.
-Enables receiving messages from WhatsApp, Telegram, and other platforms.
-"""
-
-from app.external_comms.config import (
-    ExternalCommsConfig,
-    get_config,
-    load_config,
-    save_config,
-    reload_config,
-)
-
-from app.external_comms.manager import (
-    ExternalCommsManager,
-    get_external_comms_manager,
-    initialize_manager,
-)
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage
-from app.external_comms.credentials import (
-    has_credential,
-    load_credential,
-    save_credential,
-    remove_credential,
-)
-from app.external_comms.registry import (
-    register_client,
-    get_client,
-    get_all_clients,
-    get_registered_platforms,
-)
-
-__all__ = [
-    # Config
-    "ExternalCommsConfig",
-    "get_config",
-    "load_config",
-    "save_config",
-    "reload_config",
-    # Manager
-    "ExternalCommsManager",
-    "get_external_comms_manager",
-    "initialize_manager",
-    # Base
-    "BasePlatformClient",
-    "PlatformMessage",
-    # Credentials
-    "has_credential",
-    "load_credential",
-    "save_credential",
-    "remove_credential",
-    # Registry
-    "register_client",
-    "get_client",
-    "get_all_clients",
-    "get_registered_platforms",
-]
diff --git a/app/external_comms/base.py b/app/external_comms/base.py
deleted file mode 100644
index cab67f78..00000000
--- a/app/external_comms/base.py
+++ /dev/null
@@ -1,107 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.base
-
-Base classes for platform clients.
-"""
-
-from __future__ import annotations
-
-import logging
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any, Callable, Coroutine, Dict, List, Optional
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-
-@dataclass
-class PlatformMessage:
-    """Standardized incoming message from any platform."""
-    platform: str               # e.g. "telegram", "slack", "discord"
-    sender_id: str              # Platform-specific sender/chat ID
-    sender_name: str = ""       # Human-readable name
-    text: str = ""              # Message text
-    channel_id: str = ""        # Channel/conversation/group ID (if applicable)
-    channel_name: str = ""      # Human-readable channel name
-    message_id: str = ""        # Platform-specific message ID
-    timestamp: Optional[datetime] = None
-    raw: Dict[str, Any] = field(default_factory=dict)  # Original platform payload
-
-
-# Callback type for incoming messages
-MessageCallback = Callable[[PlatformMessage], Coroutine[Any, Any, None]]
-
-
-class BasePlatformClient(ABC):
-    """
-    Abstract base class for all platform clients.
-
-    Each platform implements this with its own credential loading,
-    API calls, and optional listening/polling support.
-    """
-
-    PLATFORM_ID: str = ""  # Override in subclasses: "slack", "telegram_bot", etc.
-
-    def __init__(self):
-        self._connected = False
-        self._listening = False
-        self._message_callback: Optional[MessageCallback] = None
-
-    @property
-    def is_connected(self) -> bool:
-        return self._connected
-
-    @property
-    def is_listening(self) -> bool:
-        return self._listening
-
-    @abstractmethod
-    def has_credentials(self) -> bool:
-        """Check if credentials are available for this platform."""
-        ...
-
-    @abstractmethod
-    async def connect(self) -> None:
-        """Initialize the client and verify credentials work."""
-        ...
-
-    async def disconnect(self) -> None:
-        """Clean up resources."""
-        if self._listening:
-            await self.stop_listening()
-        self._connected = False
-
-    @abstractmethod
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """
-        Send a message on this platform.
-
-        Args:
-            recipient: Platform-specific recipient ID (chat ID, channel ID, etc.)
-            text: Message text to send.
-
-        Returns:
-            Dict with at least {"ok": True/False} and platform-specific details.
-        """
-        ...
-
-    # --- Optional listening support (for platforms with incoming messages) ---
-
-    @property
-    def supports_listening(self) -> bool:
-        """Whether this client supports receiving messages (polling/websocket)."""
-        return False
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        """Start receiving messages. Override in platforms that support it."""
-        raise NotImplementedError(f"{self.PLATFORM_ID} does not support listening")
-
-    async def stop_listening(self) -> None:
-        """Stop receiving messages. Override in platforms that support it."""
-        self._listening = False
diff --git a/app/external_comms/config.py b/app/external_comms/config.py
deleted file mode 100644
index bec98efc..00000000
--- a/app/external_comms/config.py
+++ /dev/null
@@ -1,209 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.config
-
-Configuration for external communication channels (WhatsApp, Telegram).
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-
-@dataclass
-class TelegramConfig:
-    """Configuration for Telegram integration."""
-    enabled: bool = False
-    mode: str = "bot"  # "bot" for Bot API, "mtproto" for user account
-    bot_token: str = ""
-    bot_username: str = ""
-    # MTProto settings (for user account mode)
-    api_id: str = ""
-    api_hash: str = ""
-    phone_number: str = ""
-    # Behavior settings
-    auto_reply: bool = True  # Automatically route messages to agent
-
-
-@dataclass
-class WhatsAppConfig:
-    """Configuration for WhatsApp integration."""
-    enabled: bool = False
-    mode: str = "web"  # "web" for WhatsApp Web, "business" for Business API
-    # WhatsApp Web settings
-    session_id: str = ""
-    # Business API settings
-    phone_number_id: str = ""
-    access_token: str = ""
-    # Behavior settings
-    auto_reply: bool = True  # Automatically route messages to agent
-
-
-@dataclass
-class ExternalCommsConfig:
-    """Configuration for all external communication channels."""
-    telegram: TelegramConfig = field(default_factory=TelegramConfig)
-    whatsapp: WhatsAppConfig = field(default_factory=WhatsAppConfig)
-
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "ExternalCommsConfig":
-        """Create config from dictionary."""
-        telegram_data = data.get("telegram", {})
-        whatsapp_data = data.get("whatsapp", {})
-
-        return cls(
-            telegram=TelegramConfig(
-                enabled=telegram_data.get("enabled", False),
-                mode=telegram_data.get("mode", "bot"),
-                bot_token=telegram_data.get("bot_token", ""),
-                bot_username=telegram_data.get("bot_username", ""),
-                api_id=telegram_data.get("api_id", ""),
-                api_hash=telegram_data.get("api_hash", ""),
-                phone_number=telegram_data.get("phone_number", ""),
-                auto_reply=telegram_data.get("auto_reply", True),
-            ),
-            whatsapp=WhatsAppConfig(
-                enabled=whatsapp_data.get("enabled", False),
-                mode=whatsapp_data.get("mode", "web"),
-                session_id=whatsapp_data.get("session_id", ""),
-                phone_number_id=whatsapp_data.get("phone_number_id", ""),
-                access_token=whatsapp_data.get("access_token", ""),
-                auto_reply=whatsapp_data.get("auto_reply", True),
-            ),
-        )
-
-    def to_dict(self) -> Dict[str, Any]:
-        """Convert config to dictionary."""
-        return {
-            "telegram": {
-                "enabled": self.telegram.enabled,
-                "mode": self.telegram.mode,
-                "bot_token": self.telegram.bot_token,
-                "bot_username": self.telegram.bot_username,
-                "api_id": self.telegram.api_id,
-                "api_hash": self.telegram.api_hash,
-                "phone_number": self.telegram.phone_number,
-                "auto_reply": self.telegram.auto_reply,
-            },
-            "whatsapp": {
-                "enabled": self.whatsapp.enabled,
-                "mode": self.whatsapp.mode,
-                "session_id": self.whatsapp.session_id,
-                "phone_number_id": self.whatsapp.phone_number_id,
-                "access_token": self.whatsapp.access_token,
-                "auto_reply": self.whatsapp.auto_reply,
-            },
-        }
-
-
-def load_config(config_path: Optional[Path] = None) -> ExternalCommsConfig:
-    """
-    Load external communications configuration.
-
-    Loads from config file and applies environment variable overrides.
-
-    Args:
-        config_path: Path to config JSON file. If None, uses default location.
-
-    Returns:
-        ExternalCommsConfig instance.
-    """
-    config_data = {}
-
-    # Load from file if exists
-    if config_path is None:
-        from app.config import PROJECT_ROOT
-        config_path = PROJECT_ROOT / "app" / "config" / "external_comms_config.json"
-
-    if config_path.exists():
-        try:
-            with open(config_path, "r", encoding="utf-8") as f:
-                config_data = json.load(f)
-            logger.info(f"[EXTERNAL_COMMS] Loaded config from {config_path}")
-        except Exception as e:
-            logger.warning(f"[EXTERNAL_COMMS] Failed to load config: {e}")
-
-    # Create config from file data
-    config = ExternalCommsConfig.from_dict(config_data)
-
-    # Apply environment variable overrides
-    _apply_env_overrides(config)
-
-    return config
-
-
-def _apply_env_overrides(config: ExternalCommsConfig) -> None:
-    """Apply environment variable overrides to config."""
-    # Master switch
-    if os.getenv("ENABLE_EXTERNAL_COMMS", "").lower() == "true":
-        # Individual channel toggles still apply
-        pass
-
-    # Telegram overrides
-    if os.getenv("ENABLE_TELEGRAM", "").lower() == "true":
-        config.telegram.enabled = True
-    if os.getenv("TELEGRAM_SHARED_BOT_TOKEN"):
-        config.telegram.bot_token = os.getenv("TELEGRAM_SHARED_BOT_TOKEN", "")
-    if os.getenv("TELEGRAM_SHARED_BOT_USERNAME"):
-        config.telegram.bot_username = os.getenv("TELEGRAM_SHARED_BOT_USERNAME", "")
-    if os.getenv("TELEGRAM_API_ID"):
-        config.telegram.api_id = os.getenv("TELEGRAM_API_ID", "")
-    if os.getenv("TELEGRAM_API_HASH"):
-        config.telegram.api_hash = os.getenv("TELEGRAM_API_HASH", "")
-
-    # WhatsApp overrides
-    if os.getenv("ENABLE_WHATSAPP", "").lower() == "true":
-        config.whatsapp.enabled = True
-
-
-def save_config(config: ExternalCommsConfig, config_path: Optional[Path] = None) -> None:
-    """
-    Save external communications configuration to file.
-
-    Args:
-        config: Configuration to save.
-        config_path: Path to config JSON file. If None, uses default location.
-    """
-    if config_path is None:
-        from app.config import PROJECT_ROOT
-        config_path = PROJECT_ROOT / "app" / "config" / "external_comms_config.json"
-
-    # Ensure directory exists
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-
-    try:
-        with open(config_path, "w", encoding="utf-8") as f:
-            json.dump(config.to_dict(), f, indent=2)
-        logger.info(f"[EXTERNAL_COMMS] Saved config to {config_path}")
-    except Exception as e:
-        logger.error(f"[EXTERNAL_COMMS] Failed to save config: {e}")
-
-
-# Global config instance
-_config: Optional[ExternalCommsConfig] = None
-
-
-def get_config() -> ExternalCommsConfig:
-    """Get the global external communications config."""
-    global _config
-    if _config is None:
-        _config = load_config()
-    return _config
-
-
-def reload_config() -> ExternalCommsConfig:
-    """Reload configuration from file."""
-    global _config
-    _config = load_config()
-    return _config
diff --git a/app/external_comms/credentials.py b/app/external_comms/credentials.py
deleted file mode 100644
index b1b23e78..00000000
--- a/app/external_comms/credentials.py
+++ /dev/null
@@ -1,110 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.credentials
-
-Simple JSON-file credential storage in .credentials/ folder.
-One file per platform (e.g. slack.json, notion.json).
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import stat
-from dataclasses import asdict, fields
-from pathlib import Path
-from typing import Optional, Type, TypeVar
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-T = TypeVar("T")
-
-_credentials_dir: Optional[Path] = None
-
-
-def _get_credentials_dir() -> Path:
-    """Get the .credentials directory path, creating it if needed."""
-    global _credentials_dir
-    if _credentials_dir is None:
-        from app.config import PROJECT_ROOT
-        _credentials_dir = PROJECT_ROOT / ".credentials"
-    _credentials_dir.mkdir(parents=True, exist_ok=True)
-    # Restrict directory permissions to owner only (rwx------)
-    try:
-        os.chmod(_credentials_dir, stat.S_IRWXU)
-    except OSError:
-        pass  # Best-effort on platforms that don't support chmod (e.g. Windows)
-    return _credentials_dir
-
-
-def has_credential(filename: str) -> bool:
-    """Check if a credential file exists."""
-    return (_get_credentials_dir() / filename).exists()
-
-
-def load_credential(filename: str, credential_cls: Type[T]) -> Optional[T]:
-    """
-    Load a credential from a JSON file.
-
-    Args:
-        filename: e.g. "slack.json"
-        credential_cls: Dataclass type to deserialize into.
-
-    Returns:
-        Instance of credential_cls, or None if file doesn't exist.
-    """
-    path = _get_credentials_dir() / filename
-    if not path.exists():
-        return None
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        # Only pass fields that exist on the dataclass
-        valid_fields = {fld.name for fld in fields(credential_cls)}
-        filtered = {k: v for k, v in data.items() if k in valid_fields}
-        return credential_cls(**filtered)
-    except Exception as e:
-        logger.warning(f"Failed to load credential {filename}: {e}")
-        return None
-
-
-def save_credential(filename: str, credential) -> None:
-    """
-    Save a credential dataclass to a JSON file.
-
-    Args:
-        filename: e.g. "slack.json"
-        credential: Dataclass instance to serialize.
-    """
-    path = _get_credentials_dir() / filename
-    try:
-        with open(path, "w", encoding="utf-8") as f:
-            json.dump(asdict(credential), f, indent=2, default=str)
-        # Restrict file permissions to owner read/write only (rw-------)
-        try:
-            os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
-        except OSError:
-            pass  # Best-effort on platforms that don't support chmod
-        logger.info(f"Saved credential: {filename}")
-    except Exception as e:
-        logger.error(f"Failed to save credential {filename}: {e}")
-
-
-def remove_credential(filename: str) -> bool:
-    """
-    Remove a credential file.
-
-    Returns:
-        True if file was removed, False if it didn't exist.
-    """
-    path = _get_credentials_dir() / filename
-    if path.exists():
-        path.unlink()
-        logger.info(f"Removed credential: {filename}")
-        return True
-    return False
diff --git a/app/external_comms/integration_discovery.py b/app/external_comms/integration_discovery.py
deleted file mode 100644
index 8c48a671..00000000
--- a/app/external_comms/integration_discovery.py
+++ /dev/null
@@ -1,132 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.integration_discovery
-
-Dynamic discovery of connected messaging integrations for action availability.
-Used by the ActionRouter to dynamically expose messaging actions based on
-which platforms have valid credentials.
-"""
-
-from typing import List, Dict
-
-from agent_core.utils.logger import logger
-
-
-# Maps platform client IDs to their messaging action sets
-PLATFORM_TO_ACTION_SET: Dict[str, str] = {
-    "telegram_bot": "telegram_bot",
-    "telegram_user": "telegram_user",
-    "whatsapp_web": "whatsapp",
-    "whatsapp_business": "whatsapp",
-    "discord": "discord",
-    "slack": "slack",
-    "jira": "jira",
-    "github": "github",
-    "twitter": "twitter",
-}
-
-# Maps action sets to their primary send actions for conversation mode
-# These are the basic send message actions for each platform
-ACTION_SET_SEND_ACTIONS: Dict[str, List[str]] = {
-    "telegram_bot": ["send_telegram_bot_message"],
-    "telegram_user": ["send_telegram_user_message"],
-    "whatsapp": ["send_whatsapp_web_text_message"],
-    "discord": ["send_discord_message", "send_discord_dm"],
-    "slack": ["send_slack_message"],
-    "jira": ["add_jira_comment", "create_jira_issue"],
-    "github": ["add_github_comment", "create_github_issue"],
-    "twitter": ["post_tweet", "reply_to_tweet"],
-}
-
-
-def get_connected_messaging_platforms() -> List[str]:
-    """
-    Return list of platform IDs that have valid credentials.
-
-    Dynamically discovers which messaging platforms are connected by checking
-    credentials for each registered platform client.
-
-    Returns:
-        List of platform IDs (e.g., ["telegram_bot", "whatsapp_web", "discord"])
-    """
-    try:
-        from app.external_comms.registry import get_all_clients
-
-        connected = []
-        all_clients = get_all_clients()
-
-        for platform_id, client in all_clients.items():
-            # Only include messaging platforms (those in our mapping)
-            if platform_id in PLATFORM_TO_ACTION_SET:
-                try:
-                    if client.has_credentials():
-                        connected.append(platform_id)
-                        logger.debug(f"[DISCOVERY] Platform {platform_id} has credentials")
-                except Exception as e:
-                    logger.debug(f"[DISCOVERY] Error checking credentials for {platform_id}: {e}")
-
-        return connected
-    except Exception as e:
-        logger.warning(f"[DISCOVERY] Failed to discover connected platforms: {e}")
-        return []
-
-
-def get_messaging_actions_for_platforms(platforms: List[str]) -> List[str]:
-    """
-    Return send_* action names for the specified connected platforms.
-
-    Maps platform IDs to their corresponding action sets and returns
-    the send message actions that should be available.
-
-    Args:
-        platforms: List of connected platform IDs
-
-    Returns:
-        List of action names (e.g., ["send_telegram_bot_message", "send_discord_message"])
-    """
-    # Get unique action sets from connected platforms
-    action_sets = set()
-    for platform_id in platforms:
-        if platform_id in PLATFORM_TO_ACTION_SET:
-            action_sets.add(PLATFORM_TO_ACTION_SET[platform_id])
-
-    # Collect send actions from each action set
-    actions = []
-    for action_set in action_sets:
-        if action_set in ACTION_SET_SEND_ACTIONS:
-            actions.extend(ACTION_SET_SEND_ACTIONS[action_set])
-
-    return actions
-
-
-def get_connected_platforms_summary() -> str:
-    """
-    Get a human-readable summary of connected messaging platforms.
-
-    Useful for inclusion in prompts to inform the agent which platforms
-    are available for messaging.
-
-    Returns:
-        Formatted string listing connected platforms and their actions.
-    """
-    platforms = get_connected_messaging_platforms()
-    if not platforms:
-        return "No external messaging platforms connected."
-
-    actions = get_messaging_actions_for_platforms(platforms)
-
-    # Group by action set for cleaner display
-    lines = ["Connected messaging platforms:"]
-
-    action_sets_found = set()
-    for platform_id in platforms:
-        action_set = PLATFORM_TO_ACTION_SET.get(platform_id, platform_id)
-        action_sets_found.add(action_set)
-
-    for action_set in sorted(action_sets_found):
-        set_actions = ACTION_SET_SEND_ACTIONS.get(action_set, [])
-        available = [a for a in set_actions if a in actions]
-        if available:
-            lines.append(f"- {action_set}: {', '.join(available)}")
-
-    return "\n".join(lines)
diff --git a/app/external_comms/integration_settings.py b/app/external_comms/integration_settings.py
deleted file mode 100644
index 25dfd390..00000000
--- a/app/external_comms/integration_settings.py
+++ /dev/null
@@ -1,685 +0,0 @@
-"""Integration settings management — shared by browser and TUI frontends."""
-from __future__ import annotations
-
-import asyncio
-import logging
-from typing import Any, Dict, List, Optional, Tuple
-
-logger = logging.getLogger(__name__)
-
-# Integration metadata registry with auth types and field definitions
-INTEGRATION_REGISTRY: Dict[str, Dict[str, Any]] = {
-    "google": {
-        "name": "Google Workspace",
-        "description": "Gmail, Calendar, Drive",
-        "auth_type": "oauth",
-        "fields": [],
-    },
-    "slack": {
-        "name": "Slack",
-        "description": "Team messaging",
-        "auth_type": "both",  # Has both OAuth (invite) and token (login)
-        "fields": [
-            {"key": "bot_token", "label": "Bot Token", "placeholder": "xoxb-...", "password": True},
-            {"key": "workspace_name", "label": "Workspace Name (optional)", "placeholder": "My Workspace", "password": False},
-        ],
-    },
-    "notion": {
-        "name": "Notion",
-        "description": "Notes and databases",
-        "auth_type": "both",
-        "fields": [
-            {"key": "token", "label": "Integration Token", "placeholder": "secret_...", "password": True},
-        ],
-    },
-    "linkedin": {
-        "name": "LinkedIn",
-        "description": "Professional network",
-        "auth_type": "oauth",
-        "fields": [],
-    },
-"discord": {
-        "name": "Discord",
-        "description": "Community chat",
-        "auth_type": "token",
-        "fields": [
-            {"key": "bot_token", "label": "Bot Token", "placeholder": "Enter bot token", "password": True},
-        ],
-    },
-    "telegram": {
-        "name": "Telegram",
-        "description": "Messaging platform",
-        "auth_type": "token_with_interactive",
-        "fields": [
-            {"key": "bot_token", "label": "Bot Token", "placeholder": "From @BotFather", "password": True},
-        ],
-    },
-    "whatsapp": {
-        "name": "WhatsApp",
-        "description": "Messaging via Web",
-        "auth_type": "interactive",  # Requires QR code scan
-        "fields": [],
-    },
-"whatsapp_business": {
-        "name": "WhatsApp Business",
-        "description": "WhatsApp Cloud API",
-        "auth_type": "token",
-        "fields": [
-            {"key": "access_token", "label": "Access Token", "placeholder": "Enter access token", "password": True},
-            {"key": "phone_number_id", "label": "Phone Number ID", "placeholder": "Enter phone number ID", "password": False},
-        ],
-    },
-    "jira": {
-        "name": "Jira",
-        "description": "Issue tracking and project management",
-        "auth_type": "token",
-        "fields": [
-            {"key": "domain", "label": "Jira Domain", "placeholder": "mycompany.atlassian.net", "password": False},
-            {"key": "email", "label": "Email", "placeholder": "you@example.com", "password": False},
-            {"key": "api_token", "label": "API Token", "placeholder": "Enter Jira API token", "password": True},
-        ],
-    },
-    "github": {
-        "name": "GitHub",
-        "description": "Repositories, issues, and pull requests",
-        "auth_type": "token",
-        "fields": [
-            {"key": "access_token", "label": "Personal Access Token", "placeholder": "ghp_...", "password": True},
-        ],
-    },
-    "twitter": {
-        "name": "Twitter/X",
-        "description": "Tweets, mentions, and timeline",
-        "auth_type": "token",
-        "fields": [
-            {"key": "api_key", "label": "Consumer Key", "placeholder": "Enter Consumer key", "password": True},
-            {"key": "api_secret", "label": "Consumer Secret", "placeholder": "Enter Consumer secret", "password": True},
-            {"key": "access_token", "label": "Access Token", "placeholder": "Enter access token", "password": True},
-            {"key": "access_token_secret", "label": "Access Token Secret", "placeholder": "Enter access token secret", "password": True},
-        ],
-    },
-}
-
-
-def _get_handler(integration_id: str):
-    """Get the integration handler for the given ID."""
-    from app.credentials.handlers import INTEGRATION_HANDLERS
-    return INTEGRATION_HANDLERS.get(integration_id)
-
-
-def _parse_status_accounts(status_message: str) -> List[Dict[str, str]]:
-    """Parse account info from status message.
-
-    Status messages are in format:
-    "Integration: Connected
-      - Account Name (account_id)"
-    or
-    "  Bots:
-        - BotName (bot_id)
-      Users:
-        - UserName (user_id)"
-    """
-    accounts = []
-    lines = status_message.split("\n")
-
-    for line in lines:
-        line = line.strip()
-        if line.startswith("- "):
-            # Extract account info: "- Name (id)" or "- @username (id)"
-            info = line[2:].strip()
-            if "(" in info and info.endswith(")"):
-                # Has ID in parentheses
-                name_part = info[:info.rfind("(")].strip()
-                id_part = info[info.rfind("(")+1:-1].strip()
-                accounts.append({"display": name_part, "id": id_part})
-            else:
-                # No ID, just name
-                accounts.append({"display": info, "id": info})
-
-    return accounts
-
-
-def list_integrations() -> List[Dict[str, Any]]:
-    """List all integrations with their connection status.
-
-    Returns list of dicts with:
-    - id: Integration ID
-    - name: Display name
-    - description: Short description
-    - auth_type: oauth, token, both, interactive, or token_with_interactive
-    - connected: bool
-    - accounts: list of connected accounts
-    - fields: list of input field definitions for token auth
-    """
-    results = []
-
-    for integration_id, info in INTEGRATION_REGISTRY.items():
-        handler = _get_handler(integration_id)
-        connected = False
-        accounts = []
-
-        if handler:
-            try:
-                # Run status synchronously
-                loop = asyncio.new_event_loop()
-                try:
-                    success, status_msg = loop.run_until_complete(handler.status())
-                finally:
-                    loop.close()
-
-                # Check if connected based on status message
-                if "Connected" in status_msg and "Not connected" not in status_msg:
-                    connected = True
-                    accounts = _parse_status_accounts(status_msg)
-            except Exception as e:
-                logger.warning(f"Failed to get status for {integration_id}: {e}")
-
-        results.append({
-            "id": integration_id,
-            "name": info["name"],
-            "description": info["description"],
-            "auth_type": info["auth_type"],
-            "connected": connected,
-            "accounts": accounts,
-            "fields": info.get("fields", []),
-        })
-
-    return results
-
-
-def get_integration_info(integration_id: str) -> Optional[Dict[str, Any]]:
-    """Get detailed info about a specific integration."""
-    if integration_id not in INTEGRATION_REGISTRY:
-        return None
-
-    info = INTEGRATION_REGISTRY[integration_id]
-    handler = _get_handler(integration_id)
-    connected = False
-    accounts = []
-
-    if handler:
-        try:
-            loop = asyncio.new_event_loop()
-            try:
-                success, status_msg = loop.run_until_complete(handler.status())
-            finally:
-                loop.close()
-
-            if "Connected" in status_msg and "Not connected" not in status_msg:
-                connected = True
-                accounts = _parse_status_accounts(status_msg)
-        except Exception as e:
-            logger.warning(f"Failed to get status for {integration_id}: {e}")
-
-    return {
-        "id": integration_id,
-        "name": info["name"],
-        "description": info["description"],
-        "auth_type": info["auth_type"],
-        "connected": connected,
-        "accounts": accounts,
-        "fields": info.get("fields", []),
-    }
-
-
-def get_integration_accounts(integration_id: str) -> List[Dict[str, str]]:
-    """Get list of connected accounts for an integration."""
-    info = get_integration_info(integration_id)
-    if info:
-        return info.get("accounts", [])
-    return []
-
-
-PLATFORM_MAP = {
-    "whatsapp": ["whatsapp_web"],
-    "telegram": ["telegram_bot", "telegram_user"],
-    "google": ["google_workspace"],
-    "jira": ["jira"],
-    "github": ["github"],
-    "twitter": ["twitter"],
-}
-
-
-async def _start_platform_listener(integration_id: str) -> None:
-    """Start the external comms listener for a newly connected platform."""
-    try:
-        from app.external_comms.manager import get_external_comms_manager
-        manager = get_external_comms_manager()
-        if manager:
-            platform_ids = PLATFORM_MAP.get(integration_id, [integration_id])
-            for platform_id in platform_ids:
-                await manager.start_platform(platform_id)
-    except Exception as e:
-        logger.warning(f"Failed to start listener for {integration_id}: {e}")
-
-
-async def connect_integration_token(integration_id: str, credentials: Dict[str, str]) -> Tuple[bool, str]:
-    """Connect an integration using provided credentials/tokens.
-
-    Args:
-        integration_id: The integration to connect
-        credentials: Dict of field key -> value
-
-    Returns:
-        (success, message) tuple
-    """
-    handler = _get_handler(integration_id)
-    if not handler:
-        return False, f"Unknown integration: {integration_id}"
-
-    # Build args list based on integration type
-    args = []
-
-    if integration_id == "slack":
-        bot_token = credentials.get("bot_token", "")
-        if not bot_token:
-            return False, "Bot token is required"
-        args = [bot_token]
-        workspace_name = credentials.get("workspace_name", "")
-        if workspace_name:
-            args.append(workspace_name)
-
-    elif integration_id == "notion":
-        token = credentials.get("token", "")
-        if not token:
-            return False, "Integration token is required"
-        args = [token]
-
-    elif integration_id == "discord":
-        bot_token = credentials.get("bot_token", "")
-        if not bot_token:
-            return False, "Bot token is required"
-        args = [bot_token]
-
-    elif integration_id == "telegram":
-        bot_token = credentials.get("bot_token", "")
-        if not bot_token:
-            return False, "Bot token is required"
-        args = [bot_token]
-
-    elif integration_id == "whatsapp_business":
-        access_token = credentials.get("access_token", "")
-        phone_number_id = credentials.get("phone_number_id", "")
-        if not access_token or not phone_number_id:
-            return False, "Access token and phone number ID are required"
-        args = [access_token, phone_number_id]
-
-    elif integration_id == "jira":
-        domain = credentials.get("domain", "")
-        email = credentials.get("email", "")
-        api_token = credentials.get("api_token", "")
-        if not domain or not email or not api_token:
-            return False, "Domain, email, and API token are required"
-        args = [domain, email, api_token]
-
-    elif integration_id == "github":
-        access_token = credentials.get("access_token", "")
-        if not access_token:
-            return False, "Personal access token is required"
-        args = [access_token]
-
-    elif integration_id == "twitter":
-        api_key = credentials.get("api_key", "")
-        api_secret = credentials.get("api_secret", "")
-        access_token = credentials.get("access_token", "")
-        access_token_secret = credentials.get("access_token_secret", "")
-        if not all([api_key, api_secret, access_token, access_token_secret]):
-            return False, "All four Twitter API credentials are required"
-        args = [api_key, api_secret, access_token, access_token_secret]
-
-    else:
-        return False, f"Token-based login not supported for {integration_id}"
-
-    try:
-        success, message = await handler.login(args)
-        if success:
-            await _start_platform_listener(integration_id)
-        return success, message
-    except Exception as e:
-        logger.error(f"Failed to connect {integration_id}: {e}")
-        return False, f"Connection failed: {str(e)}"
-
-
-async def connect_integration_oauth(integration_id: str) -> Tuple[bool, str]:
-    """Start OAuth flow for an integration.
-
-    Args:
-        integration_id: The integration to connect via OAuth
-
-    Returns:
-        (success, message) tuple
-    """
-    handler = _get_handler(integration_id)
-    if not handler:
-        return False, f"Unknown integration: {integration_id}"
-
-    auth_type = INTEGRATION_REGISTRY.get(integration_id, {}).get("auth_type", "")
-
-    if auth_type not in ("oauth", "both"):
-        return False, f"OAuth not supported for {integration_id}"
-
-    try:
-        # For integrations with both OAuth and token, OAuth is via invite
-        if auth_type == "both" and hasattr(handler, "invite"):
-            success, message = await handler.invite([])
-        else:
-            success, message = await handler.login([])
-        if success:
-            await _start_platform_listener(integration_id)
-        return success, message
-    except Exception as e:
-        logger.error(f"OAuth failed for {integration_id}: {e}")
-        return False, f"OAuth failed: {str(e)}"
-
-
-async def disconnect_integration(integration_id: str, account_id: Optional[str] = None) -> Tuple[bool, str]:
-    """Disconnect an integration account.
-
-    Args:
-        integration_id: The integration to disconnect
-        account_id: Optional specific account to disconnect
-
-    Returns:
-        (success, message) tuple
-    """
-    handler = _get_handler(integration_id)
-    if not handler:
-        return False, f"Unknown integration: {integration_id}"
-
-    try:
-        args = [account_id] if account_id else []
-        return await handler.logout(args)
-    except Exception as e:
-        logger.error(f"Failed to disconnect {integration_id}: {e}")
-        return False, f"Disconnect failed: {str(e)}"
-
-
-async def connect_integration_interactive(integration_id: str) -> Tuple[bool, str]:
-    """Start interactive connection flow (e.g. WhatsApp QR code scan).
-
-    Args:
-        integration_id: The integration to connect
-
-    Returns:
-        (success, message) tuple
-    """
-    handler = _get_handler(integration_id)
-    if not handler:
-        return False, f"Unknown integration: {integration_id}"
-
-    auth_type = INTEGRATION_REGISTRY.get(integration_id, {}).get("auth_type", "")
-
-    if auth_type not in ("interactive", "token_with_interactive"):
-        return False, f"Interactive login not supported for {integration_id}"
-
-    try:
-        if hasattr(handler, "handle"):
-            # Prefer "login-qr" for handlers that support it, fall back to "login"
-            subs = getattr(handler, "subcommands", [])
-            sub = "login-qr" if "login-qr" in subs else "login"
-            success, message = await handler.handle(sub, [])
-        else:
-            success, message = await handler.login([])
-        if success:
-            await _start_platform_listener(integration_id)
-        return success, message
-    except Exception as e:
-        logger.error(f"Interactive login failed for {integration_id}: {e}")
-        return False, f"Connection failed: {str(e)}"
-
-
-def get_integration_auth_type(integration_id: str) -> str:
-    """Get the auth type for an integration."""
-    return INTEGRATION_REGISTRY.get(integration_id, {}).get("auth_type", "token")
-
-
-def get_integration_fields(integration_id: str) -> List[Dict[str, Any]]:
-    """Get the input fields for token-based auth."""
-    return INTEGRATION_REGISTRY.get(integration_id, {}).get("fields", [])
-
-
-# =====================
-# WhatsApp QR Code Flow
-# =====================
-
-# Store active WhatsApp bridge sessions for QR code flow
-_whatsapp_sessions: Dict[str, Any] = {}
-
-
-async def start_whatsapp_qr_session() -> Dict[str, Any]:
-    """Start the WhatsApp bridge and return QR code data.
-
-    Uses the whatsapp-web.js Node bridge so that the QR scan authenticates
-    the same session used for message listening.
-
-    Returns dict with:
-    - success: bool
-    - session_id: str (if success)
-    - qr_code: str (base64 image data, if available)
-    - status: str (qr_ready, connected, error, etc.)
-    - message: str (error or status message)
-    """
-    global _whatsapp_sessions
-
-    try:
-        from app.external_comms.platforms.whatsapp_bridge.client import get_whatsapp_bridge
-    except ImportError:
-        return {
-            "success": False,
-            "status": "error",
-            "message": "WhatsApp bridge not available. Ensure Node.js >= 18 is installed.",
-        }
-
-    try:
-        bridge = get_whatsapp_bridge()
-
-        # Start bridge if not already running
-        if not bridge.is_running:
-            await bridge.start()
-
-        # Wait for either QR code or ready (already authenticated)
-        event_type, event_data = await bridge.wait_for_qr_or_ready(timeout=60.0)
-
-        if event_type == "ready":
-            # Already authenticated — save credential and report connected
-            from app.external_comms.platforms.whatsapp_web import WhatsAppWebCredential, CREDENTIAL_FILE
-            from app.external_comms.credentials import save_credential
-
-            owner_phone = bridge.owner_phone or ""
-            owner_name = bridge.owner_name or ""
-            save_credential(CREDENTIAL_FILE, WhatsAppWebCredential(
-                session_id="bridge",
-                owner_phone=owner_phone,
-                owner_name=owner_name,
-            ))
-
-            display = owner_phone or owner_name or "connected"
-            return {
-                "success": True,
-                "session_id": "bridge",
-                "qr_code": "",
-                "status": "connected",
-                "message": f"WhatsApp already connected: +{display}",
-            }
-
-        if event_type == "qr":
-            # Generate QR code image from the QR string
-            qr_data = (event_data or {}).get("qr_data_url", "")
-
-            # If bridge didn't provide a data URL, generate one from the QR string
-            if not qr_data:
-                qr_string = (event_data or {}).get("qr_string", "")
-                if qr_string:
-                    try:
-                        import qrcode
-                        import io
-                        import base64
-                        qr = qrcode.QRCode(border=1)
-                        qr.add_data(qr_string)
-                        qr.make(fit=True)
-                        img = qr.make_image(fill_color="black", back_color="white")
-                        buf = io.BytesIO()
-                        img.save(buf, format="PNG")
-                        qr_data = f"data:image/png;base64,{base64.b64encode(buf.getvalue()).decode()}"
-                    except Exception as e:
-                        logger.warning(f"Failed to generate QR image: {e}")
-
-            if not qr_data:
-                await bridge.stop()
-                return {
-                    "success": False,
-                    "status": "error",
-                    "message": "Failed to generate QR code.",
-                }
-
-            # Ensure it's a proper data URL
-            if qr_data and not qr_data.startswith("data:"):
-                qr_data = f"data:image/png;base64,{qr_data}"
-
-            # Store bridge reference for status polling
-            session_id = "bridge"
-            _whatsapp_sessions[session_id] = bridge
-
-            return {
-                "success": True,
-                "session_id": session_id,
-                "qr_code": qr_data,
-                "status": "qr_ready",
-                "message": "Scan the QR code with your WhatsApp mobile app",
-            }
-
-        # Timeout
-        await bridge.stop()
-        return {
-            "success": False,
-            "status": "error",
-            "message": "Timed out waiting for WhatsApp bridge.",
-        }
-
-    except Exception as e:
-        logger.error(f"Failed to start WhatsApp session: {e}")
-        return {
-            "success": False,
-            "status": "error",
-            "message": f"Failed to start session: {str(e)}",
-        }
-
-
-async def check_whatsapp_session_status(session_id: str) -> Dict[str, Any]:
-    """Check the status of a WhatsApp bridge QR session.
-
-    Returns dict with:
-    - success: bool
-    - status: str (qr_ready, connected, error, disconnected)
-    - connected: bool
-    - message: str
-    """
-    global _whatsapp_sessions
-
-    bridge = _whatsapp_sessions.get(session_id)
-    if bridge is None:
-        return {
-            "success": False,
-            "status": "error",
-            "connected": False,
-            "message": "Session not found. Please start a new session.",
-        }
-
-    try:
-        if bridge.is_ready:
-            # Bridge authenticated — save credential, stop bridge, start listener
-            try:
-                from app.external_comms.platforms.whatsapp_web import WhatsAppWebCredential, CREDENTIAL_FILE
-                from app.external_comms.credentials import save_credential
-
-                owner_phone = bridge.owner_phone or ""
-                owner_name = bridge.owner_name or ""
-                save_credential(CREDENTIAL_FILE, WhatsAppWebCredential(
-                    session_id="bridge",
-                    owner_phone=owner_phone,
-                    owner_name=owner_name,
-                ))
-
-                # Clean up stored session — keep bridge running
-                # (start_platform will reuse it if still running and ready)
-                del _whatsapp_sessions[session_id]
-
-                # Start the WhatsApp listener (will reuse running bridge)
-                await _start_platform_listener("whatsapp")
-
-                display = owner_phone or owner_name or "connected"
-                return {
-                    "success": True,
-                    "status": "connected",
-                    "connected": True,
-                    "message": f"WhatsApp connected: +{display}",
-                }
-            except Exception as e:
-                logger.error(f"Failed to store WhatsApp credential: {e}")
-                return {
-                    "success": False,
-                    "status": "error",
-                    "connected": False,
-                    "message": f"Connected but failed to save: {str(e)}",
-                }
-
-        elif not bridge.is_running:
-            # Bridge crashed or stopped
-            if session_id in _whatsapp_sessions:
-                del _whatsapp_sessions[session_id]
-            return {
-                "success": False,
-                "status": "error",
-                "connected": False,
-                "message": "WhatsApp bridge stopped unexpectedly. Please try again.",
-            }
-
-        else:
-            # Still waiting for QR scan
-            return {
-                "success": True,
-                "status": "qr_ready",
-                "connected": False,
-                "message": "Waiting for QR code scan...",
-            }
-
-    except Exception as e:
-        logger.error(f"Failed to check WhatsApp session status: {e}")
-        return {
-            "success": False,
-            "status": "error",
-            "connected": False,
-            "message": f"Status check failed: {str(e)}",
-        }
-
-
-def cancel_whatsapp_session(session_id: str) -> Dict[str, Any]:
-    """Cancel a WhatsApp QR session and stop the bridge.
-
-    Returns dict with:
-    - success: bool
-    - message: str
-    """
-    global _whatsapp_sessions
-
-    bridge = _whatsapp_sessions.pop(session_id, None)
-    if bridge is not None:
-        # Stop the bridge in the background
-        try:
-            import asyncio
-            loop = asyncio.get_event_loop()
-            if loop.is_running():
-                asyncio.ensure_future(bridge.stop())
-            else:
-                loop.run_until_complete(bridge.stop())
-        except Exception:
-            pass
-        return {
-            "success": True,
-            "message": "Session cancelled.",
-        }
-
-    return {
-        "success": True,
-        "message": "Session not found or already cancelled.",
-    }
diff --git a/app/external_comms/manager.py b/app/external_comms/manager.py
deleted file mode 100644
index f54fc5a9..00000000
--- a/app/external_comms/manager.py
+++ /dev/null
@@ -1,306 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.manager
-
-Manager for external communication channels.
-Uses the platform registry to discover and start all platforms that support listening.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from typing import TYPE_CHECKING, Any, Dict, Optional
-
-from app.external_comms.base import PlatformMessage
-from app.external_comms.config import get_config
-
-if TYPE_CHECKING:
-    from app.agent_base import AgentBase
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-
-def _import_all_platforms() -> None:
-    """Import all platform modules to trigger @register_client decorators."""
-    # Each import registers the client class in the registry
-    platform_modules = [
-        "app.external_comms.platforms.telegram_bot",
-        "app.external_comms.platforms.telegram_user",
-        "app.external_comms.platforms.slack",
-        "app.external_comms.platforms.discord",
-        "app.external_comms.platforms.whatsapp_web",
-        "app.external_comms.platforms.whatsapp_business",
-        "app.external_comms.platforms.gmail",
-        "app.external_comms.platforms.notion",
-        "app.external_comms.platforms.linkedin",
-        "app.external_comms.platforms.outlook",
-        "app.external_comms.platforms.google_workspace",
-        "app.external_comms.platforms.jira",
-        "app.external_comms.platforms.github",
-        "app.external_comms.platforms.twitter",
-    ]
-    import importlib
-    for mod in platform_modules:
-        try:
-            importlib.import_module(mod)
-        except Exception:
-            pass  # Platform not installed or missing deps — skip silently
-
-
-class ExternalCommsManager:
-    """
-    Manager for all external communication channels.
-
-    Discovers platforms with listening support from the registry,
-    starts them if they have credentials, and routes incoming messages
-    to the agent's _handle_external_event method.
-    """
-
-    def __init__(self, agent: "AgentBase"):
-        self._agent = agent
-        self._config = get_config()
-        self._active_clients: Dict[str, Any] = {}
-        self._running = False
-
-    async def start(self) -> None:
-        """Start all platforms that support listening and have credentials."""
-        if self._running:
-            return
-
-        logger.info("[EXTERNAL_COMMS] Starting external communications manager...")
-
-        # Ensure all platforms are registered
-        _import_all_platforms()
-
-        from app.external_comms.registry import get_all_clients
-
-        started = []
-        all_clients = get_all_clients()
-        logger.info(f"[EXTERNAL_COMMS] Registered platforms: {list(all_clients.keys())}")
-        for platform_id, client in all_clients.items():
-            if not client.supports_listening:
-                continue
-            if not client.has_credentials():
-                logger.info(f"[EXTERNAL_COMMS] {platform_id} supports listening but has no credentials, skipping")
-                continue
-
-            try:
-                await client.start_listening(self._handle_platform_message)
-                if client.is_listening:
-                    self._active_clients[platform_id] = client
-                    started.append(platform_id)
-                    logger.info(f"[EXTERNAL_COMMS] Started listening on {platform_id}")
-                else:
-                    logger.warning(f"[EXTERNAL_COMMS] {platform_id} start_listening returned but not actually listening")
-            except Exception as e:
-                logger.warning(f"[EXTERNAL_COMMS] Failed to start {platform_id}: {e}")
-
-        self._running = True
-        if started:
-            logger.info(f"[EXTERNAL_COMMS] Active channels: {started}")
-        else:
-            logger.info("[EXTERNAL_COMMS] No external channels started")
-
-    async def start_platform(self, platform_id: str) -> bool:
-        """Start listening on a specific platform (e.g. after it was just connected).
-
-        If the platform is already in active_clients but not actually listening
-        (stale entry from a failed startup), it will be removed and re-started.
-
-        Returns True if the platform was successfully started.
-        """
-        # Check if already listening (truly active, not stale)
-        if platform_id in self._active_clients:
-            client = self._active_clients[platform_id]
-            if client.is_listening:
-                return True  # Already listening
-            # Stale entry — remove and re-start
-            logger.info(f"[EXTERNAL_COMMS] Removing stale entry for {platform_id}")
-            del self._active_clients[platform_id]
-
-        _import_all_platforms()
-
-        from app.external_comms.registry import get_client
-
-        client = get_client(platform_id)
-        if client is None:
-            logger.warning(f"[EXTERNAL_COMMS] Platform '{platform_id}' not found in registry")
-            return False
-
-        if not client.supports_listening:
-            return False
-
-        if not client.has_credentials():
-            return False
-
-        try:
-            await client.start_listening(self._handle_platform_message)
-            if client.is_listening:
-                self._active_clients[platform_id] = client
-                logger.info(f"[EXTERNAL_COMMS] Started listening on {platform_id} (post-connect)")
-                return True
-            else:
-                logger.warning(f"[EXTERNAL_COMMS] {platform_id} start_listening returned but not actually listening")
-                return False
-        except Exception as e:
-            logger.warning(f"[EXTERNAL_COMMS] Failed to start {platform_id}: {e}")
-            return False
-
-    async def stop(self) -> None:
-        """Stop all listening clients."""
-        if not self._running:
-            return
-
-        logger.info("[EXTERNAL_COMMS] Stopping external communications manager...")
-
-        for platform_id, client in self._active_clients.items():
-            try:
-                await client.stop_listening()
-            except Exception as e:
-                logger.warning(f"[EXTERNAL_COMMS] Error stopping {platform_id}: {e}")
-
-        self._active_clients.clear()
-        self._running = False
-        logger.info("[EXTERNAL_COMMS] All channels stopped")
-
-    async def _handle_platform_message(self, msg: PlatformMessage) -> None:
-        """Convert a PlatformMessage into the legacy payload format and route to agent."""
-        payload = {
-            "source": msg.platform.replace("_", " ").title(),
-            "integrationType": msg.platform,
-            "contactId": msg.sender_id,
-            "contactName": msg.sender_name or msg.sender_id,
-            "messageBody": msg.text,
-            "channelId": msg.channel_id,
-            "channelName": msg.channel_name,
-            "messageId": msg.message_id,
-            "is_self_message": msg.raw.get("is_self_message", False),
-            "raw": msg.raw,
-        }
-
-        source = payload["source"]
-        contact_name = payload["contactName"]
-        message_body = payload["messageBody"]
-
-        logger.info(
-            f"[EXTERNAL_COMMS] Received message from {source}: "
-            f"{contact_name}: {message_body[:50]}..."
-        )
-
-        try:
-            await self._agent._handle_external_event(payload)
-        except Exception as e:
-            logger.error(f"[EXTERNAL_COMMS] Error handling message: {e}")
-
-    def get_status(self) -> Dict[str, Any]:
-        """Get status of all channels."""
-        return {
-            "running": self._running,
-            "channels": {
-                name: {"running": client.is_listening}
-                for name, client in self._active_clients.items()
-            },
-        }
-
-    async def reload(self) -> Dict[str, Any]:
-        """
-        Hot-reload external communications configuration.
-
-        This method:
-        1. Reloads the config from external_comms_config.json
-        2. Stops clients that are no longer enabled
-        3. Starts clients that are newly enabled
-
-        Returns:
-            Dictionary with reload results.
-        """
-        from app.external_comms.config import reload_config
-        from app.external_comms.registry import get_all_clients
-
-        result = {
-            "success": True,
-            "stopped": [],
-            "started": [],
-            "message": "",
-        }
-
-        try:
-            # Reload config from file
-            self._config = reload_config()
-            logger.info("[EXTERNAL_COMMS] Configuration reloaded")
-
-            # Get current state
-            currently_active = set(self._active_clients.keys())
-            _import_all_platforms()
-            all_clients = get_all_clients()
-
-            # Determine which platforms should be active based on new config
-            should_be_active = set()
-            for platform_id, client in all_clients.items():
-                if not client.supports_listening:
-                    continue
-                if not client.has_credentials():
-                    continue
-                should_be_active.add(platform_id)
-
-            # Stop platforms that should no longer be active
-            to_stop = currently_active - should_be_active
-            for platform_id in to_stop:
-                try:
-                    client = self._active_clients.get(platform_id)
-                    if client:
-                        await client.stop_listening()
-                        del self._active_clients[platform_id]
-                        result["stopped"].append(platform_id)
-                        logger.info(f"[EXTERNAL_COMMS] Stopped {platform_id}")
-                except Exception as e:
-                    logger.warning(f"[EXTERNAL_COMMS] Error stopping {platform_id}: {e}")
-
-            # Start platforms that should now be active but aren't
-            to_start = should_be_active - currently_active
-            for platform_id in to_start:
-                try:
-                    client = all_clients.get(platform_id)
-                    if client:
-                        await client.start_listening(self._handle_platform_message)
-                        if client.is_listening:
-                            self._active_clients[platform_id] = client
-                            result["started"].append(platform_id)
-                            logger.info(f"[EXTERNAL_COMMS] Started {platform_id}")
-                except Exception as e:
-                    logger.warning(f"[EXTERNAL_COMMS] Error starting {platform_id}: {e}")
-
-            result["message"] = (
-                f"Reload complete. Stopped: {len(result['stopped'])}, "
-                f"Started: {len(result['started'])}, "
-                f"Active: {len(self._active_clients)}"
-            )
-            logger.info(f"[EXTERNAL_COMMS] {result['message']}")
-
-        except Exception as e:
-            result["success"] = False
-            result["message"] = f"Reload failed: {e}"
-            logger.error(f"[EXTERNAL_COMMS] Reload failed: {e}")
-
-        return result
-
-
-# Global manager instance
-_manager: Optional[ExternalCommsManager] = None
-
-
-def get_external_comms_manager() -> Optional[ExternalCommsManager]:
-    """Get the global external communications manager."""
-    return _manager
-
-
-def initialize_manager(agent: "AgentBase") -> ExternalCommsManager:
-    """Initialize and return the global external communications manager."""
-    global _manager
-    _manager = ExternalCommsManager(agent)
-    return _manager
diff --git a/app/external_comms/platforms/__init__.py b/app/external_comms/platforms/__init__.py
deleted file mode 100644
index e8689d00..00000000
--- a/app/external_comms/platforms/__init__.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.platforms
-
-Platform client implementations.
-Import individual platform modules to register them with the registry.
-"""
diff --git a/app/external_comms/platforms/discord.py b/app/external_comms/platforms/discord.py
deleted file mode 100644
index 6670641e..00000000
--- a/app/external_comms/platforms/discord.py
+++ /dev/null
@@ -1,965 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Discord API client — combined bot + user + voice via httpx.
-
-Supports three modes:
-- Bot mode: uses ``Bot {token}`` auth for server/bot operations.
-- User mode: uses bare token auth for self-bot / personal automation.
-- Both: store both tokens and call whichever set of methods you need.
-
-Voice methods are thin stubs that lazily import the
-``DiscordVoiceManager`` from agent_core to avoid pulling in
-discord.py / PyNaCl / FFmpeg unless actually needed.
-
-WARNING: Automating user accounts (self-bots) may violate Discord's
-Terms of Service. Use user-mode methods at your own risk.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-from urllib.parse import quote as _url_quote
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-DISCORD_API_BASE = "https://discord.com/api/v10"
-DISCORD_GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json"
-CREDENTIAL_FILE = "discord.json"
-
-# Gateway intents: GUILD_MESSAGES | DIRECT_MESSAGES | MESSAGE_CONTENT
-GATEWAY_INTENTS = (1 << 9) | (1 << 12) | (1 << 15)  # 37376
-
-
-@dataclass
-class DiscordCredential:
-    bot_token: str = ""
-    user_token: str = ""
-
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Client
-# ═══════════════════════════════════════════════════════════════════════════════
-
-@register_client
-class DiscordClient(BasePlatformClient):
-    """Unified Discord client exposing bot, user, and voice operations."""
-
-    PLATFORM_ID = "discord"
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cred: Optional[DiscordCredential] = None
-        self._ws = None
-        self._ws_task: Optional[asyncio.Task] = None
-        self._heartbeat_task: Optional[asyncio.Task] = None
-        self._heartbeat_interval: float = 41.25
-        self._last_sequence: Optional[int] = None
-        self._bot_user_id: Optional[str] = None
-        self._catchup_done: bool = False
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> DiscordCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, DiscordCredential)
-        if self._cred is None:
-            raise RuntimeError("No Discord credentials. Use /discord login first.")
-        return self._cred
-
-    def _bot_token(self) -> str:
-        cred = self._load()
-        if not cred.bot_token:
-            raise RuntimeError("No Discord bot_token configured.")
-        return cred.bot_token
-
-    def _user_token(self) -> str:
-        cred = self._load()
-        if not cred.user_token:
-            raise RuntimeError("No Discord user_token configured.")
-        return cred.user_token
-
-    def _bot_headers(self) -> Dict[str, str]:
-        return {
-            "Authorization": f"Bot {self._bot_token()}",
-            "Content-Type": "application/json",
-        }
-
-    def _user_headers(self) -> Dict[str, str]:
-        return {
-            "Authorization": self._user_token(),
-            "Content-Type": "application/json",
-        }
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    # ------------------------------------------------------------------
-    # Gateway listening (WebSocket)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        """Connect to the Discord Gateway and listen for messages."""
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        cred = self._load()
-        if not cred.bot_token:
-            raise RuntimeError("No Discord bot token for Gateway connection")
-
-        # Verify token by fetching bot user info
-        bot_info = self.get_bot_user()
-        if "error" in bot_info:
-            raise RuntimeError(f"Invalid Discord bot token: {bot_info.get('error')}")
-        self._bot_user_id = bot_info["result"]["id"]
-
-        self._listening = True
-        self._catchup_done = False
-        self._ws_task = asyncio.create_task(self._gateway_loop())
-        logger.info(
-            f"[DISCORD] Gateway listener started for bot {bot_info['result'].get('username', 'unknown')}"
-        )
-
-    async def stop_listening(self) -> None:
-        """Disconnect from the Gateway."""
-        if not self._listening:
-            return
-
-        self._listening = False
-
-        if self._heartbeat_task and not self._heartbeat_task.done():
-            self._heartbeat_task.cancel()
-            try:
-                await self._heartbeat_task
-            except asyncio.CancelledError:
-                pass
-        self._heartbeat_task = None
-
-        if self._ws:
-            try:
-                await self._ws.close()
-            except Exception:
-                pass
-            self._ws = None
-
-        if self._ws_task and not self._ws_task.done():
-            self._ws_task.cancel()
-            try:
-                await self._ws_task
-            except asyncio.CancelledError:
-                pass
-        self._ws_task = None
-
-        logger.info("[DISCORD] Gateway listener stopped")
-
-    async def _gateway_loop(self) -> None:
-        """Main Gateway reconnection loop."""
-        import aiohttp
-
-        while self._listening:
-            try:
-                async with aiohttp.ClientSession() as session:
-                    async with session.ws_connect(DISCORD_GATEWAY_URL) as ws:
-                        self._ws = ws
-                        await self._handle_gateway(ws)
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[DISCORD] Gateway error: {e}")
-                if self._listening:
-                    await asyncio.sleep(5)
-
-    async def _handle_gateway(self, ws) -> None:
-        """Handle a single Gateway session."""
-        import aiohttp as _aiohttp
-        async for msg in ws:
-            if not self._listening:
-                break
-            if msg.type == _aiohttp.WSMsgType.TEXT:
-                try:
-                    data = json.loads(msg.data)
-                    await self._process_gateway_event(ws, data)
-                except Exception as e:
-                    logger.error(f"[DISCORD] Error processing Gateway event: {e}")
-            elif msg.type in (_aiohttp.WSMsgType.ERROR, _aiohttp.WSMsgType.CLOSED):
-                break
-
-    async def _process_gateway_event(self, ws, data: dict) -> None:
-        """Process a single Gateway event."""
-        op = data.get("op")
-        t = data.get("t")
-        d = data.get("d")
-        s = data.get("s")
-
-        if s is not None:
-            self._last_sequence = s
-
-        if op == 10:  # Hello — start heartbeat + identify
-            self._heartbeat_interval = d["heartbeat_interval"] / 1000.0
-            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop(ws))
-            # Send Identify
-            await ws.send_json({
-                "op": 2,
-                "d": {
-                    "token": self._bot_token(),
-                    "intents": GATEWAY_INTENTS,
-                    "properties": {
-                        "os": "windows",
-                        "browser": "craftosbot",
-                        "device": "craftosbot",
-                    },
-                },
-            })
-
-        elif op == 0:  # Dispatch
-            if t == "READY":
-                logger.info("[DISCORD] Gateway READY")
-                # Mark catchup as done after a short delay to skip any
-                # initial burst of cached messages
-                asyncio.get_event_loop().call_later(2.0, self._mark_catchup_done)
-
-            elif t == "MESSAGE_CREATE" and d:
-                await self._handle_message_create(d)
-
-        elif op == 1:  # Heartbeat request
-            await ws.send_json({"op": 1, "d": self._last_sequence})
-
-        elif op == 9:  # Invalid session
-            logger.warning("[DISCORD] Invalid session, reconnecting...")
-            await ws.close()
-
-        elif op == 7:  # Reconnect
-            logger.info("[DISCORD] Gateway requested reconnect")
-            await ws.close()
-
-    def _mark_catchup_done(self) -> None:
-        self._catchup_done = True
-        logger.info("[DISCORD] Catchup complete — now dispatching messages")
-
-    async def _heartbeat_loop(self, ws) -> None:
-        """Send heartbeats at the required interval."""
-        try:
-            while self._listening:
-                await ws.send_json({"op": 1, "d": self._last_sequence})
-                await asyncio.sleep(self._heartbeat_interval)
-        except asyncio.CancelledError:
-            pass
-        except Exception:
-            pass
-
-    async def _handle_message_create(self, d: dict) -> None:
-        """Process a MESSAGE_CREATE event."""
-        # Ignore messages from the bot itself
-        author = d.get("author", {})
-        if author.get("id") == self._bot_user_id:
-            return
-
-        # Ignore bot messages
-        if author.get("bot"):
-            return
-
-        content = d.get("content", "")
-        if not content:
-            return
-
-        # Skip during catchup
-        if not self._catchup_done:
-            return
-
-        author_name = author.get("username", "Unknown")
-        channel_id = d.get("channel_id", "")
-        guild_id = d.get("guild_id", "")
-
-        # Determine channel name
-        channel_name = ""
-        if guild_id:
-            # It's a guild channel — we don't have the name cached, use ID
-            channel_name = f"#{channel_id}"
-        else:
-            # DM
-            channel_name = "DM"
-
-        ts = None
-        if d.get("timestamp"):
-            try:
-                ts = datetime.fromisoformat(d["timestamp"])
-            except Exception:
-                pass
-
-        platform_msg = PlatformMessage(
-            platform="discord",
-            sender_id=author.get("id", ""),
-            sender_name=author_name,
-            text=content,
-            channel_id=channel_id,
-            channel_name=channel_name,
-            message_id=d.get("id", ""),
-            timestamp=ts,
-            raw={"guild_id": guild_id, "is_self_message": False},
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a message to a channel (uses bot token by default)."""
-        return self.bot_send_message(channel_id=recipient, content=text, **kwargs)
-
-    # ══════════════════════════════════════════════════════════════════════
-    # BOT METHODS
-    # ══════════════════════════════════════════════════════════════════════
-
-    # --- Bot info -------------------------------------------------------
-
-    def get_bot_user(self) -> Dict[str, Any]:
-        """Get the bot's own user information."""
-        try:
-            r = httpx.get(f"{DISCORD_API_BASE}/users/@me", headers=self._bot_headers(), timeout=15)
-            if r.status_code == 200:
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "id": data.get("id"),
-                        "username": data.get("username"),
-                        "discriminator": data.get("discriminator"),
-                        "avatar": data.get("avatar"),
-                        "bot": data.get("bot", True),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_bot_guilds(self, limit: int = 100) -> Dict[str, Any]:
-        """Get guilds (servers) the bot is a member of."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/@me/guilds",
-                headers=self._bot_headers(),
-                params={"limit": limit},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": {"guilds": r.json()}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # --- Channels -------------------------------------------------------
-
-    def get_guild_channels(self, guild_id: str) -> Dict[str, Any]:
-        """Get all channels in a guild."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/guilds/{guild_id}/channels",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                channels = r.json()
-                text_channels = [c for c in channels if c.get("type") == 0]
-                voice_channels = [c for c in channels if c.get("type") == 2]
-                categories = [c for c in channels if c.get("type") == 4]
-                return {
-                    "ok": True,
-                    "result": {
-                        "all_channels": channels,
-                        "text_channels": text_channels,
-                        "voice_channels": voice_channels,
-                        "categories": categories,
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_channel(self, channel_id: str) -> Dict[str, Any]:
-        """Get a channel by ID."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/channels/{channel_id}",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # --- Messages -------------------------------------------------------
-
-    def bot_send_message(
-        self,
-        channel_id: str,
-        content: str,
-        embed: Optional[Dict[str, Any]] = None,
-        reply_to: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Send a message to a channel as the bot."""
-        payload: Dict[str, Any] = {"content": content}
-        if embed:
-            payload["embeds"] = [embed]
-        if reply_to:
-            payload["message_reference"] = {"message_id": reply_to}
-
-        try:
-            r = httpx.post(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
-                headers=self._bot_headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "message_id": data.get("id"),
-                        "channel_id": data.get("channel_id"),
-                        "content": data.get("content"),
-                        "timestamp": data.get("timestamp"),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_messages(
-        self,
-        channel_id: str,
-        limit: int = 50,
-        before: Optional[str] = None,
-        after: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Get messages from a channel (bot token)."""
-        params: Dict[str, Any] = {"limit": min(limit, 100)}
-        if before:
-            params["before"] = before
-        if after:
-            params["after"] = after
-
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
-                headers=self._bot_headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                messages = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "messages": [
-                            {
-                                "id": m.get("id"),
-                                "content": m.get("content"),
-                                "author": {
-                                    "id": m.get("author", {}).get("id"),
-                                    "username": m.get("author", {}).get("username"),
-                                    "bot": m.get("author", {}).get("bot", False),
-                                },
-                                "timestamp": m.get("timestamp"),
-                                "attachments": m.get("attachments", []),
-                                "embeds": m.get("embeds", []),
-                            }
-                            for m in messages
-                        ],
-                        "count": len(messages),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def edit_message(
-        self,
-        channel_id: str,
-        message_id: str,
-        content: str,
-    ) -> Dict[str, Any]:
-        """Edit a message the bot sent."""
-        try:
-            r = httpx.patch(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}",
-                headers=self._bot_headers(),
-                json={"content": content},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def delete_message(
-        self,
-        channel_id: str,
-        message_id: str,
-    ) -> Dict[str, Any]:
-        """Delete a message."""
-        try:
-            r = httpx.delete(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 204:
-                return {"ok": True, "result": {"deleted": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # --- Direct messages ------------------------------------------------
-
-    def create_dm_channel(self, recipient_id: str) -> Dict[str, Any]:
-        """Create (or retrieve) a DM channel with a user (bot token)."""
-        try:
-            r = httpx.post(
-                f"{DISCORD_API_BASE}/users/@me/channels",
-                headers=self._bot_headers(),
-                json={"recipient_id": recipient_id},
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "channel_id": data.get("id"),
-                        "type": data.get("type"),
-                        "recipients": data.get("recipients", []),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def send_dm(
-        self,
-        recipient_id: str,
-        content: str,
-        embed: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Send a DM to a user via the bot."""
-        dm_result = self.create_dm_channel(recipient_id)
-        if "error" in dm_result:
-            return dm_result
-        channel_id = dm_result["result"]["channel_id"]
-        return self.bot_send_message(channel_id, content, embed)
-
-    # --- Users & members ------------------------------------------------
-
-    def get_user(self, user_id: str) -> Dict[str, Any]:
-        """Get a user by ID (bot token)."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/{user_id}",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_guild_member(self, guild_id: str, user_id: str) -> Dict[str, Any]:
-        """Get a member of a guild."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/guilds/{guild_id}/members/{user_id}",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def list_guild_members(self, guild_id: str, limit: int = 100) -> Dict[str, Any]:
-        """List members of a guild."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/guilds/{guild_id}/members",
-                headers=self._bot_headers(),
-                params={"limit": min(limit, 1000)},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": {"members": r.json()}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # --- Reactions -------------------------------------------------------
-
-    def add_reaction(
-        self,
-        channel_id: str,
-        message_id: str,
-        emoji: str,
-    ) -> Dict[str, Any]:
-        """Add a reaction to a message."""
-        encoded_emoji = _url_quote(emoji, safe="")
-        try:
-            r = httpx.put(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}/reactions/{encoded_emoji}/@me",
-                headers=self._bot_headers(),
-                timeout=15,
-            )
-            if r.status_code == 204:
-                return {"ok": True, "result": {"added": True, "emoji": emoji}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ══════════════════════════════════════════════════════════════════════
-    # USER-ACCOUNT METHODS (self-bot / personal automation)
-    # ══════════════════════════════════════════════════════════════════════
-
-    def user_get_current_user(self) -> Dict[str, Any]:
-        """Get the authenticated user's own profile."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/@me",
-                headers=self._user_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "id": data.get("id"),
-                        "username": data.get("username"),
-                        "discriminator": data.get("discriminator"),
-                        "email": data.get("email"),
-                        "avatar": data.get("avatar"),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_get_guilds(self, limit: int = 100) -> Dict[str, Any]:
-        """Get guilds the user account is in."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/@me/guilds",
-                headers=self._user_headers(),
-                params={"limit": limit},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": {"guilds": r.json()}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_get_dm_channels(self) -> Dict[str, Any]:
-        """Get the user's DM channel list."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/@me/channels",
-                headers=self._user_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                channels = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "dm_channels": [
-                            {
-                                "id": c.get("id"),
-                                "type": c.get("type"),
-                                "recipients": [
-                                    {
-                                        "id": rec.get("id"),
-                                        "username": rec.get("username"),
-                                    }
-                                    for rec in c.get("recipients", [])
-                                ],
-                                "last_message_id": c.get("last_message_id"),
-                            }
-                            for c in channels
-                        ],
-                        "count": len(channels),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_send_message(
-        self,
-        channel_id: str,
-        content: str,
-        reply_to: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Send a message as the user account."""
-        payload: Dict[str, Any] = {"content": content}
-        if reply_to:
-            payload["message_reference"] = {"message_id": reply_to}
-
-        try:
-            r = httpx.post(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
-                headers=self._user_headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "message_id": data.get("id"),
-                        "channel_id": data.get("channel_id"),
-                        "content": data.get("content"),
-                        "timestamp": data.get("timestamp"),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_get_messages(
-        self,
-        channel_id: str,
-        limit: int = 50,
-        before: Optional[str] = None,
-        after: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Get messages from a channel (user token)."""
-        params: Dict[str, Any] = {"limit": min(limit, 100)}
-        if before:
-            params["before"] = before
-        if after:
-            params["after"] = after
-
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
-                headers=self._user_headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                messages = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "messages": [
-                            {
-                                "id": m.get("id"),
-                                "content": m.get("content"),
-                                "author": {
-                                    "id": m.get("author", {}).get("id"),
-                                    "username": m.get("author", {}).get("username"),
-                                },
-                                "timestamp": m.get("timestamp"),
-                                "attachments": m.get("attachments", []),
-                            }
-                            for m in messages
-                        ],
-                        "count": len(messages),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_send_dm(
-        self,
-        recipient_id: str,
-        content: str,
-    ) -> Dict[str, Any]:
-        """Send a DM as the user account."""
-        # Create / retrieve the DM channel first
-        try:
-            r = httpx.post(
-                f"{DISCORD_API_BASE}/users/@me/channels",
-                headers=self._user_headers(),
-                json={"recipient_id": recipient_id},
-                timeout=15,
-            )
-            if r.status_code not in (200, 201):
-                return {"error": f"API error: {r.status_code}", "details": r.text}
-            channel_id = r.json().get("id")
-        except Exception as e:
-            return {"error": str(e)}
-
-        return self.user_send_message(channel_id, content)
-
-    def user_get_relationships(self) -> Dict[str, Any]:
-        """Get the user's relationships (friends, blocked, pending)."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/users/@me/relationships",
-                headers=self._user_headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                relationships = r.json()
-                friends = [rel for rel in relationships if rel.get("type") == 1]
-                blocked = [rel for rel in relationships if rel.get("type") == 2]
-                incoming = [rel for rel in relationships if rel.get("type") == 3]
-                outgoing = [rel for rel in relationships if rel.get("type") == 4]
-                return {
-                    "ok": True,
-                    "result": {
-                        "friends": [
-                            {
-                                "id": rel.get("id"),
-                                "username": rel.get("user", {}).get("username"),
-                            }
-                            for rel in friends
-                        ],
-                        "blocked": blocked,
-                        "incoming_requests": incoming,
-                        "outgoing_requests": outgoing,
-                        "total_friends": len(friends),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def user_search_guild_messages(
-        self,
-        guild_id: str,
-        query: str,
-        limit: int = 25,
-    ) -> Dict[str, Any]:
-        """Search messages in a guild (user token — not available to bots)."""
-        try:
-            r = httpx.get(
-                f"{DISCORD_API_BASE}/guilds/{guild_id}/messages/search",
-                headers=self._user_headers(),
-                params={"content": query, "limit": limit},
-                timeout=30,
-            )
-            if r.status_code == 200:
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "total_results": data.get("total_results"),
-                        "messages": data.get("messages", []),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ══════════════════════════════════════════════════════════════════════
-    # VOICE STUBS  (lazy-import to avoid requiring discord.py at load time)
-    # ══════════════════════════════════════════════════════════════════════
-
-    def _get_voice_manager(self):
-        """Lazily import and instantiate the DiscordVoiceManager."""
-        from app.external_comms.platforms.discord_voice_helpers import DiscordVoiceManager
-        return DiscordVoiceManager(self._bot_token())
-
-    async def join_voice(
-        self,
-        guild_id: str,
-        channel_id: str,
-        self_deaf: bool = False,
-        self_mute: bool = False,
-    ) -> Dict[str, Any]:
-        """Join a voice channel.
-
-        Requires discord.py[voice], PyNaCl, and FFmpeg.
-        """
-        try:
-            from app.external_comms.platforms.discord_voice_helpers import DiscordVoiceManager
-            manager = DiscordVoiceManager(self._bot_token())
-            await manager.start()
-            return await manager.join_voice(guild_id, channel_id, self_deaf=self_deaf, self_mute=self_mute)
-        except ImportError as e:
-            return {"error": f"Voice dependencies not installed: {e}"}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def leave_voice(self, guild_id: str) -> Dict[str, Any]:
-        """Leave the voice channel in a guild.
-
-        Requires discord.py[voice], PyNaCl, and FFmpeg.
-        """
-        try:
-            from app.external_comms.platforms.discord_voice_helpers import DiscordVoiceManager
-            manager = DiscordVoiceManager(self._bot_token())
-            return await manager.leave_voice(guild_id)
-        except ImportError as e:
-            return {"error": f"Voice dependencies not installed: {e}"}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def speak_tts(
-        self,
-        guild_id: str,
-        text: str,
-        tts_provider: str = "openai",
-        voice: str = "alloy",
-    ) -> Dict[str, Any]:
-        """Speak text in a voice channel via TTS.
-
-        Requires discord.py[voice], PyNaCl, FFmpeg, and a TTS provider.
-        """
-        try:
-            from app.external_comms.platforms.discord_voice_helpers import DiscordVoiceManager
-            manager = DiscordVoiceManager(self._bot_token())
-            return await manager.speak_text(guild_id, text, tts_provider=tts_provider, voice=voice)
-        except ImportError as e:
-            return {"error": f"Voice dependencies not installed: {e}"}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_voice_status(self, guild_id: str) -> Dict[str, Any]:
-        """Get the current voice connection status for a guild.
-
-        Requires discord.py[voice].
-        """
-        try:
-            from app.external_comms.platforms.discord_voice_helpers import DiscordVoiceManager
-            manager = DiscordVoiceManager(self._bot_token())
-            return manager.get_voice_status(guild_id)
-        except ImportError as e:
-            return {"error": f"Voice dependencies not installed: {e}"}
-        except Exception as e:
-            return {"error": str(e)}
diff --git a/app/external_comms/platforms/github.py b/app/external_comms/platforms/github.py
deleted file mode 100644
index bcd760ac..00000000
--- a/app/external_comms/platforms/github.py
+++ /dev/null
@@ -1,538 +0,0 @@
-# -*- coding: utf-8 -*-
-"""GitHub REST API client — direct HTTP via httpx.
-
-Supports personal access token (PAT) authentication.
-Listening is implemented via polling for notifications and
-events on watched repositories. An optional **watch_tag** lets
-users restrict triggers to issue/PR comments mentioning a tag
-(e.g. ``@craftbot``).
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-GITHUB_API = "https://api.github.com"
-CREDENTIAL_FILE = "github.json"
-
-POLL_INTERVAL = 15      # seconds between polls
-RETRY_DELAY = 30        # seconds to wait after a poll error
-
-
-@dataclass
-class GitHubCredential:
-    access_token: str = ""
-    username: str = ""
-    # Listener settings
-    watch_repos: List[str] = field(default_factory=list)   # e.g. ["owner/repo"]
-    watch_tag: str = ""  # e.g. "@craftbot" — only trigger on comments containing this
-
-
-@register_client
-class GitHubClient(BasePlatformClient):
-    """GitHub platform client with notification polling."""
-
-    PLATFORM_ID = "github"
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cred: Optional[GitHubCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._last_modified: Optional[str] = None  # If-Modified-Since header
-        self._seen_ids: set = set()
-        self._catchup_done: bool = False
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> GitHubCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, GitHubCredential)
-        if self._cred is None:
-            raise RuntimeError("No GitHub credentials. Use /github login first.")
-        return self._cred
-
-    def _headers(self) -> Dict[str, str]:
-        cred = self._load()
-        return {
-            "Authorization": f"Bearer {cred.access_token}",
-            "Accept": "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        }
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Create a comment on an issue/PR.
-
-        Args:
-            recipient: "{owner}/{repo}#{number}" e.g. "octocat/hello-world#1"
-            text: Comment body (markdown).
-        """
-        try:
-            # Parse "owner/repo#number"
-            repo_part, number = recipient.rsplit("#", 1)
-            return await self.create_comment(repo_part.strip(), int(number), text)
-        except (ValueError, IndexError):
-            return {"error": f"Invalid recipient format. Use 'owner/repo#number', got: {recipient}"}
-
-    # ------------------------------------------------------------------
-    # Watch tag / repos configuration
-    # ------------------------------------------------------------------
-
-    def get_watch_tag(self) -> str:
-        return self._load().watch_tag
-
-    def set_watch_tag(self, tag: str) -> None:
-        cred = self._load()
-        cred.watch_tag = tag.strip()
-        save_credential(CREDENTIAL_FILE, cred)
-        self._cred = cred
-        logger.info(f"[GITHUB] Watch tag set to: {cred.watch_tag or '(disabled)'}")
-
-    def get_watch_repos(self) -> List[str]:
-        return list(self._load().watch_repos)
-
-    def set_watch_repos(self, repos: List[str]) -> None:
-        cred = self._load()
-        cred.watch_repos = [r.strip() for r in repos if r.strip()]
-        save_credential(CREDENTIAL_FILE, cred)
-        self._cred = cred
-        logger.info(f"[GITHUB] Watch repos set to: {cred.watch_repos or '(all)'}")
-
-    # ------------------------------------------------------------------
-    # Listening (notification polling)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        self._load()
-
-        # Verify token
-        me = await self.get_authenticated_user()
-        if "error" in me:
-            raise RuntimeError(f"Invalid GitHub token: {me.get('error')}")
-
-        username = me.get("result", {}).get("login", "unknown")
-        logger.info(f"[GITHUB] Authenticated as: {username}")
-
-        # Save username
-        cred = self._load()
-        if cred.username != username:
-            cred.username = username
-            save_credential(CREDENTIAL_FILE, cred)
-            self._cred = cred
-
-        # Catchup: mark current time so we skip old notifications
-        self._last_modified = datetime.now(timezone.utc).strftime("%a, %d %b %Y %H:%M:%S GMT")
-        self._catchup_done = True
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-
-        tag_info = cred.watch_tag or "(disabled — all events)"
-        repos_info = ", ".join(cred.watch_repos) if cred.watch_repos else "(all repos)"
-        logger.info(f"[GITHUB] Poller started — tag: {tag_info} | repos: {repos_info}")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[GITHUB] Poller stopped")
-
-    async def _poll_loop(self) -> None:
-        while self._listening:
-            try:
-                await self._check_notifications()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[GITHUB] Poll error: {e}")
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _check_notifications(self) -> None:
-        headers = self._headers()
-        if self._last_modified:
-            headers["If-Modified-Since"] = self._last_modified
-
-        cred = self._load()
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(
-                f"{GITHUB_API}/notifications",
-                headers=headers,
-                params={"all": "false", "participating": "true"},
-                timeout=30,
-            )
-
-            if resp.status_code == 304:
-                return  # No new notifications
-            if resp.status_code == 401:
-                logger.warning("[GITHUB] Authentication expired (401)")
-                return
-            if resp.status_code != 200:
-                logger.warning(f"[GITHUB] Notifications API error: {resp.status_code}")
-                return
-
-            # Update Last-Modified for next poll
-            lm = resp.headers.get("Last-Modified")
-            if lm:
-                self._last_modified = lm
-
-            notifications = resp.json()
-
-            for notif in notifications:
-                notif_id = notif.get("id", "")
-                if notif_id in self._seen_ids:
-                    continue
-                self._seen_ids.add(notif_id)
-
-                # Filter by watched repos
-                repo_full = notif.get("repository", {}).get("full_name", "")
-                if cred.watch_repos and repo_full not in cred.watch_repos:
-                    continue
-
-                await self._dispatch_notification(client, notif)
-
-            # Cap seen set
-            if len(self._seen_ids) > 500:
-                self._seen_ids = set(list(self._seen_ids)[-200:])
-
-    async def _dispatch_notification(self, client: httpx.AsyncClient, notif: Dict[str, Any]) -> None:
-        if not self._message_callback:
-            return
-
-        cred = self._load()
-        reason = notif.get("reason", "")
-        subject = notif.get("subject", {})
-        subject_type = subject.get("type", "")  # Issue, PullRequest, etc.
-        subject_title = subject.get("title", "")
-        subject_url = subject.get("url", "")
-        repo = notif.get("repository", {})
-        repo_full = repo.get("full_name", "")
-
-        # Fetch the latest comment if there's a comment URL
-        latest_comment_url = subject.get("latest_comment_url", "")
-        comment_body = ""
-        comment_author = ""
-        if latest_comment_url:
-            try:
-                cr = await client.get(latest_comment_url, headers=self._headers(), timeout=15)
-                if cr.status_code == 200:
-                    comment_data = cr.json()
-                    comment_body = comment_data.get("body", "")
-                    comment_author = comment_data.get("user", {}).get("login", "")
-            except Exception:
-                pass
-
-        # Watch tag filtering
-        watch_tag = cred.watch_tag
-        if watch_tag:
-            if not comment_body or watch_tag.lower() not in comment_body.lower():
-                return  # Skip — no matching tag in comment
-
-            # Extract instruction after the tag
-            tag_lower = watch_tag.lower()
-            idx = comment_body.lower().find(tag_lower)
-            instruction = comment_body[idx + len(watch_tag):].strip() if idx >= 0 else comment_body
-
-            text_parts = [
-                f"[{repo_full}] {subject_type}: {subject_title}",
-                f"Comment by @{comment_author}: {instruction}",
-            ]
-
-            platform_msg = PlatformMessage(
-                platform="github",
-                sender_id=comment_author,
-                sender_name=comment_author,
-                text="\n".join(text_parts),
-                channel_id=repo_full,
-                channel_name=repo_full,
-                message_id=notif.get("id", ""),
-                timestamp=datetime.now(timezone.utc),
-                raw={
-                    "notification": notif,
-                    "trigger": "comment_tag",
-                    "tag": watch_tag,
-                    "instruction": instruction,
-                    "comment_body": comment_body,
-                    "comment_author": comment_author,
-                },
-            )
-
-            await self._message_callback(platform_msg)
-            logger.info(f"[GITHUB] Tag '{watch_tag}' matched in {repo_full} by @{comment_author}: {instruction[:80]}...")
-            return
-
-        # No watch tag — dispatch all notifications
-        text_parts = [
-            f"[{repo_full}] {subject_type}: {subject_title}",
-            f"Reason: {reason}",
-        ]
-        if comment_body:
-            text_parts.append(f"Comment by @{comment_author}: {comment_body[:300]}")
-
-        platform_msg = PlatformMessage(
-            platform="github",
-            sender_id=comment_author or "",
-            sender_name=comment_author or reason,
-            text="\n".join(text_parts),
-            channel_id=repo_full,
-            channel_name=repo_full,
-            message_id=notif.get("id", ""),
-            timestamp=datetime.now(timezone.utc),
-            raw=notif,
-        )
-
-        await self._message_callback(platform_msg)
-
-    # ------------------------------------------------------------------
-    # GitHub REST API methods
-    # ------------------------------------------------------------------
-
-    async def get_authenticated_user(self) -> Dict[str, Any]:
-        """Get the authenticated user's info."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(f"{GITHUB_API}/user", headers=self._headers(), timeout=15)
-                if resp.status_code == 200:
-                    data = resp.json()
-                    return {"ok": True, "result": {"login": data.get("login"), "name": data.get("name"), "id": data.get("id")}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def list_repos(self, per_page: int = 30, sort: str = "updated") -> Dict[str, Any]:
-        """List repositories for the authenticated user."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{GITHUB_API}/user/repos",
-                    headers=self._headers(),
-                    params={"per_page": per_page, "sort": sort},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    repos = [{"full_name": r.get("full_name"), "name": r.get("name"), "private": r.get("private"), "description": r.get("description", "")} for r in resp.json()]
-                    return {"ok": True, "result": {"repos": repos}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_repo(self, owner_repo: str) -> Dict[str, Any]:
-        """Get repository info."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(f"{GITHUB_API}/repos/{owner_repo}", headers=self._headers(), timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def list_issues(self, owner_repo: str, state: str = "open", per_page: int = 30) -> Dict[str, Any]:
-        """List issues for a repository."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{GITHUB_API}/repos/{owner_repo}/issues",
-                    headers=self._headers(),
-                    params={"state": state, "per_page": per_page},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    issues = [
-                        {
-                            "number": i.get("number"),
-                            "title": i.get("title"),
-                            "state": i.get("state"),
-                            "user": i.get("user", {}).get("login", ""),
-                            "labels": [l.get("name") for l in i.get("labels", [])],
-                            "assignees": [a.get("login") for a in i.get("assignees", [])],
-                            "created_at": i.get("created_at"),
-                            "updated_at": i.get("updated_at"),
-                            "is_pr": "pull_request" in i,
-                        }
-                        for i in resp.json()
-                    ]
-                    return {"ok": True, "result": {"issues": issues}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_issue(self, owner_repo: str, number: int) -> Dict[str, Any]:
-        """Get a specific issue or PR."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(f"{GITHUB_API}/repos/{owner_repo}/issues/{number}", headers=self._headers(), timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def create_issue(self, owner_repo: str, title: str, body: str = "", labels: Optional[List[str]] = None, assignees: Optional[List[str]] = None) -> Dict[str, Any]:
-        """Create a new issue."""
-        payload: Dict[str, Any] = {"title": title}
-        if body:
-            payload["body"] = body
-        if labels:
-            payload["labels"] = labels
-        if assignees:
-            payload["assignees"] = assignees
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(f"{GITHUB_API}/repos/{owner_repo}/issues", headers=self._headers(), json=payload, timeout=15)
-                if resp.status_code in (200, 201):
-                    data = resp.json()
-                    return {"ok": True, "result": {"number": data.get("number"), "html_url": data.get("html_url"), "title": data.get("title")}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def create_comment(self, owner_repo: str, number: int, body: str) -> Dict[str, Any]:
-        """Create a comment on an issue or PR."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{GITHUB_API}/repos/{owner_repo}/issues/{number}/comments",
-                    headers=self._headers(),
-                    json={"body": body},
-                    timeout=15,
-                )
-                if resp.status_code in (200, 201):
-                    data = resp.json()
-                    return {"ok": True, "result": {"id": data.get("id"), "html_url": data.get("html_url")}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def list_pull_requests(self, owner_repo: str, state: str = "open", per_page: int = 30) -> Dict[str, Any]:
-        """List pull requests for a repository."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{GITHUB_API}/repos/{owner_repo}/pulls",
-                    headers=self._headers(),
-                    params={"state": state, "per_page": per_page},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    prs = [
-                        {
-                            "number": p.get("number"),
-                            "title": p.get("title"),
-                            "state": p.get("state"),
-                            "user": p.get("user", {}).get("login", ""),
-                            "head": p.get("head", {}).get("ref", ""),
-                            "base": p.get("base", {}).get("ref", ""),
-                            "draft": p.get("draft", False),
-                            "created_at": p.get("created_at"),
-                        }
-                        for p in resp.json()
-                    ]
-                    return {"ok": True, "result": {"pull_requests": prs}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def search_issues(self, query: str, per_page: int = 20) -> Dict[str, Any]:
-        """Search issues and PRs."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{GITHUB_API}/search/issues",
-                    headers=self._headers(),
-                    params={"q": query, "per_page": per_page},
-                    timeout=30,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    items = [
-                        {
-                            "number": i.get("number"),
-                            "title": i.get("title"),
-                            "state": i.get("state"),
-                            "repo": i.get("repository_url", "").split("/repos/")[-1] if i.get("repository_url") else "",
-                            "user": i.get("user", {}).get("login", ""),
-                            "html_url": i.get("html_url"),
-                        }
-                        for i in data.get("items", [])
-                    ]
-                    return {"ok": True, "result": {"total_count": data.get("total_count", 0), "items": items}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def add_labels(self, owner_repo: str, number: int, labels: List[str]) -> Dict[str, Any]:
-        """Add labels to an issue/PR."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{GITHUB_API}/repos/{owner_repo}/issues/{number}/labels",
-                    headers=self._headers(),
-                    json={"labels": labels},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    return {"ok": True, "result": {"labels_added": labels}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def close_issue(self, owner_repo: str, number: int) -> Dict[str, Any]:
-        """Close an issue."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.patch(
-                    f"{GITHUB_API}/repos/{owner_repo}/issues/{number}",
-                    headers=self._headers(),
-                    json={"state": "closed"},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    return {"ok": True, "result": {"closed": True, "number": number}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
diff --git a/app/external_comms/platforms/google_workspace.py b/app/external_comms/platforms/google_workspace.py
deleted file mode 100644
index bb1e9976..00000000
--- a/app/external_comms/platforms/google_workspace.py
+++ /dev/null
@@ -1,658 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Google Workspace client — Gmail + Calendar + Drive via httpx."""
-
-from __future__ import annotations
-
-import asyncio
-import base64
-import logging
-import mimetypes
-import os
-import time
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from email import encoders
-from email.mime.base import MIMEBase
-from email.mime.multipart import MIMEMultipart
-from email.mime.text import MIMEText
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-GMAIL_API_BASE = "https://gmail.googleapis.com/gmail/v1"
-CALENDAR_API_BASE = "https://www.googleapis.com/calendar/v3"
-DRIVE_API_BASE = "https://www.googleapis.com/drive/v3"
-GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
-CREDENTIAL_FILE = "google.json"
-
-POLL_INTERVAL = 5       # seconds between Gmail polls
-RETRY_DELAY = 10        # seconds to wait after a poll error
-
-
-@dataclass
-class GoogleCredential:
-    access_token: str = ""
-    refresh_token: str = ""
-    token_expiry: float = 0.0
-    client_id: str = ""
-    client_secret: str = ""
-    email: str = ""
-
-
-@register_client
-class GoogleWorkspaceClient(BasePlatformClient):
-    PLATFORM_ID = "google_workspace"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[GoogleCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._history_id: Optional[str] = None
-        self._seen_message_ids: set = set()
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> GoogleCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, GoogleCredential)
-        if self._cred is None:
-            raise RuntimeError("No Google credentials. Configure google.json first.")
-        return self._cred
-
-    def _ensure_token(self) -> str:
-        """Return a valid access token, refreshing if expired."""
-        cred = self._load()
-        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
-            result = self.refresh_access_token()
-            if result:
-                return result
-        return cred.access_token
-
-    def refresh_access_token(self) -> Optional[str]:
-        cred = self._load()
-        if not all([cred.client_id, cred.client_secret, cred.refresh_token]):
-            return None
-        try:
-            r = httpx.post(
-                GOOGLE_TOKEN_URL,
-                data={
-                    "client_id": cred.client_id,
-                    "client_secret": cred.client_secret,
-                    "refresh_token": cred.refresh_token,
-                    "grant_type": "refresh_token",
-                },
-                timeout=15,
-            )
-            if r.status_code == 200:
-                data = r.json()
-                cred.access_token = data["access_token"]
-                cred.token_expiry = time.time() + data.get("expires_in", 3600) - 60
-                save_credential(CREDENTIAL_FILE, cred)
-                self._cred = cred
-                return cred.access_token
-        except Exception:
-            pass
-        return None
-
-    def _headers(self) -> Dict[str, str]:
-        return {
-            "Authorization": f"Bearer {self._ensure_token()}",
-            "Content-Type": "application/json",
-        }
-
-    def _auth_header(self) -> Dict[str, str]:
-        """Authorization header only (no Content-Type)."""
-        return {"Authorization": f"Bearer {self._ensure_token()}"}
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send an email (maps the generic interface to send_email)."""
-        subject = kwargs.get("subject", "")
-        result = self.send_email(to=recipient, subject=subject, body=text)
-        return result
-
-    # ------------------------------------------------------------------
-    # Listening support (Gmail polling via History API)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        self._load()
-
-        # Verify token works and get current historyId for catchup
-        try:
-            profile = await self._async_get_profile()
-            self._history_id = profile.get("historyId")
-            logger.info(f"[GOOGLE] Gmail profile: {profile.get('emailAddress')}, historyId: {self._history_id}")
-        except Exception as e:
-            raise RuntimeError(f"Failed to connect to Gmail: {e}")
-
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-        logger.info("[GOOGLE] Gmail poller started")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[GOOGLE] Gmail poller stopped")
-
-    async def _async_get_profile(self) -> Dict[str, Any]:
-        """Get Gmail profile (async)."""
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(
-                f"{GMAIL_API_BASE}/users/me/profile",
-                headers=self._auth_header(),
-                timeout=15,
-            )
-            if resp.status_code != 200:
-                raise RuntimeError(f"Gmail profile API error: {resp.status_code}")
-            return resp.json()
-
-    async def _poll_loop(self) -> None:
-        """Poll Gmail for new messages using the History API."""
-        logger.info("[GOOGLE] Catchup complete — watching for new emails")
-
-        while self._listening:
-            try:
-                await self._check_history()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[GOOGLE] Poll error: {e}")
-                # If historyId is stale, reset it
-                if "404" in str(e) or "historyId" in str(e).lower():
-                    try:
-                        profile = await self._async_get_profile()
-                        self._history_id = profile.get("historyId")
-                        logger.info(f"[GOOGLE] Reset historyId to {self._history_id}")
-                    except Exception:
-                        pass
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _check_history(self) -> None:
-        """Check Gmail history for new messages since last historyId."""
-        if not self._history_id:
-            return
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(
-                f"{GMAIL_API_BASE}/users/me/history",
-                headers=self._auth_header(),
-                params={
-                    "startHistoryId": self._history_id,
-                    "historyTypes": "messageAdded",
-                    "labelId": "INBOX",
-                },
-                timeout=15,
-            )
-
-            if resp.status_code == 404:
-                # historyId too old — reset
-                raise RuntimeError("historyId expired (404)")
-
-            if resp.status_code != 200:
-                logger.warning(f"[GOOGLE] history.list error: {resp.status_code}")
-                return
-
-            data = resp.json()
-            new_history_id = data.get("historyId")
-            if new_history_id:
-                self._history_id = new_history_id
-
-            history_records = data.get("history", [])
-            if not history_records:
-                return
-
-            # Collect unique new message IDs
-            new_msg_ids = []
-            for record in history_records:
-                for added in record.get("messagesAdded", []):
-                    msg = added.get("message", {})
-                    msg_id = msg.get("id", "")
-                    labels = msg.get("labelIds", [])
-                    # Only process INBOX messages we haven't seen
-                    if msg_id and "INBOX" in labels and msg_id not in self._seen_message_ids:
-                        new_msg_ids.append(msg_id)
-                        self._seen_message_ids.add(msg_id)
-
-            # Cap seen set size
-            if len(self._seen_message_ids) > 500:
-                self._seen_message_ids = set(list(self._seen_message_ids)[-200:])
-
-            # Fetch and dispatch each new message
-            for msg_id in new_msg_ids:
-                try:
-                    await self._fetch_and_dispatch(client, msg_id)
-                except Exception as e:
-                    logger.debug(f"[GOOGLE] Error processing message {msg_id}: {e}")
-
-    async def _fetch_and_dispatch(self, client: httpx.AsyncClient, msg_id: str) -> None:
-        """Fetch a single Gmail message and dispatch to callback."""
-        resp = await client.get(
-            f"{GMAIL_API_BASE}/users/me/messages/{msg_id}",
-            headers=self._auth_header(),
-            params=[("format", "metadata"), ("metadataHeaders", "From"), ("metadataHeaders", "Subject"), ("metadataHeaders", "Date")],
-            timeout=15,
-        )
-        if resp.status_code != 200:
-            return
-
-        msg = resp.json()
-        headers = {h["name"]: h["value"] for h in msg.get("payload", {}).get("headers", [])}
-
-        from_header = headers.get("From", "")
-        subject = headers.get("Subject", "(no subject)")
-        snippet = msg.get("snippet", "")
-
-        # Parse "Name <email>" format
-        sender_name = from_header
-        sender_email = from_header
-        if "<" in from_header and ">" in from_header:
-            parts = from_header.rsplit("<", 1)
-            sender_name = parts[0].strip().strip('"')
-            sender_email = parts[1].rstrip(">").strip()
-
-        # Skip messages sent by ourselves
-        cred = self._load()
-        if sender_email.lower() == (cred.email or "").lower():
-            return
-
-        # Parse date
-        timestamp = None
-        date_str = headers.get("Date", "")
-        if date_str:
-            try:
-                from email.utils import parsedate_to_datetime
-                timestamp = parsedate_to_datetime(date_str)
-                if timestamp.tzinfo is None:
-                    timestamp = timestamp.replace(tzinfo=timezone.utc)
-            except Exception:
-                pass
-
-        text = f"Subject: {subject}\n{snippet}" if snippet else f"Subject: {subject}"
-
-        platform_msg = PlatformMessage(
-            platform="google_workspace",
-            sender_id=sender_email,
-            sender_name=sender_name or sender_email,
-            text=text,
-            channel_id=msg.get("threadId", ""),
-            message_id=msg_id,
-            timestamp=timestamp,
-            raw=msg,
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    # ==================================================================
-    # Gmail
-    # ==================================================================
-
-    @staticmethod
-    def _encode_email(
-        to_email: str,
-        from_email: str,
-        subject: str,
-        body: str,
-        attachments: Optional[List[str]] = None,
-    ) -> str:
-        """Build a MIME message and return it as a base64 URL-safe string."""
-        msg = MIMEMultipart()
-        msg["to"] = to_email
-        msg["from"] = from_email
-        msg["subject"] = subject
-
-        msg.attach(MIMEText(body, "plain"))
-
-        if attachments:
-            for file_path in attachments:
-                if not os.path.isfile(file_path):
-                    continue
-                mime_type, _ = mimetypes.guess_type(file_path)
-                if mime_type is None:
-                    mime_type = "application/octet-stream"
-                maintype, subtype = mime_type.split("/", 1)
-
-                with open(file_path, "rb") as f:
-                    part = MIMEBase(maintype, subtype)
-                    part.set_payload(f.read())
-                    encoders.encode_base64(part)
-                    part.add_header(
-                        "Content-Disposition",
-                        f'attachment; filename="{os.path.basename(file_path)}"',
-                    )
-                    msg.attach(part)
-
-        return base64.urlsafe_b64encode(msg.as_bytes()).decode()
-
-    def send_email(
-        self,
-        to: str,
-        subject: str,
-        body: str,
-        from_email: Optional[str] = None,
-        attachments: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """Send an email via the Gmail API."""
-        cred = self._load()
-        sender = from_email or cred.email
-        raw = self._encode_email(to, sender, subject, body, attachments)
-        try:
-            r = httpx.post(
-                f"{GMAIL_API_BASE}/users/me/messages/send",
-                headers=self._headers(),
-                json={"raw": raw},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def list_emails(self, n: int = 5, unread_only: bool = True) -> Dict[str, Any]:
-        """List the top *n* recent emails from the inbox."""
-        params: Dict[str, Any] = {
-            "maxResults": n,
-            "labelIds": ["INBOX"],
-        }
-        if unread_only:
-            params["q"] = "is:unread"
-        try:
-            r = httpx.get(
-                f"{GMAIL_API_BASE}/users/me/messages",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                messages = r.json().get("messages", [])
-                return {"ok": True, "result": messages}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_email(self, message_id: str, full_body: bool = False) -> Dict[str, Any]:
-        """Get detailed information about a specific email message."""
-        format_type = "full" if full_body else "metadata"
-        params = {
-            "format": format_type,
-            "metadataHeaders": ["From", "To", "Subject", "Date"],
-        }
-        try:
-            r = httpx.get(
-                f"{GMAIL_API_BASE}/users/me/messages/{message_id}",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code != 200:
-                return {"error": f"API error: {r.status_code}", "details": r.text}
-
-            msg = r.json()
-            email_info: Dict[str, Any] = {
-                "id": msg.get("id"),
-                "snippet": msg.get("snippet", ""),
-                "headers": {
-                    h["name"]: h["value"]
-                    for h in msg.get("payload", {}).get("headers", [])
-                },
-            }
-
-            if full_body and "parts" in msg.get("payload", {}):
-                for part in msg["payload"]["parts"]:
-                    if (
-                        part.get("mimeType") == "text/plain"
-                        and "data" in part.get("body", {})
-                    ):
-                        data = part["body"]["data"]
-                        email_info["body"] = base64.urlsafe_b64decode(
-                            data.encode("ASCII")
-                        ).decode("utf-8")
-                        break
-
-            return {"ok": True, "result": email_info}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def read_top_emails(self, n: int = 5, full_body: bool = False) -> Dict[str, Any]:
-        """Convenience: list recent emails then fetch details for each."""
-        listing = self.list_emails(n=n, unread_only=False)
-        if "error" in listing:
-            return listing
-        messages = listing.get("result", [])
-        emails: List[Dict[str, Any]] = []
-        for msg in messages:
-            detail = self.get_email(msg["id"], full_body=full_body)
-            if "error" not in detail:
-                emails.append(detail.get("result", detail))
-            else:
-                emails.append(detail)
-        return {"ok": True, "result": emails}
-
-    # ==================================================================
-    # Calendar
-    # ==================================================================
-
-    def create_meet_event(
-        self,
-        calendar_id: str = "primary",
-        event_data: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Create a calendar event (with optional Google Meet conference)."""
-        try:
-            r = httpx.post(
-                f"{CALENDAR_API_BASE}/calendars/{calendar_id}/events",
-                headers=self._headers(),
-                params={"conferenceDataVersion": 1},
-                json=event_data or {},
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            try:
-                detail = r.json()
-            except Exception:
-                detail = r.text
-            return {"error": f"API error: {r.status_code}", "details": detail}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def check_availability(
-        self,
-        calendar_id: str = "primary",
-        time_min: Optional[str] = None,
-        time_max: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Query Google Calendar freebusy endpoint."""
-        payload = {
-            "timeMin": time_min,
-            "timeMax": time_max,
-            "items": [{"id": calendar_id}],
-        }
-        try:
-            r = httpx.post(
-                f"{CALENDAR_API_BASE}/freeBusy",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            try:
-                detail = r.json()
-            except Exception:
-                detail = r.text
-            return {"error": f"API error: {r.status_code}", "details": detail}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ==================================================================
-    # Drive
-    # ==================================================================
-
-    def list_drive_files(
-        self,
-        folder_id: str,
-        fields: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """List files inside a Drive folder."""
-        params = {
-            "q": f"'{folder_id}' in parents and trashed = false",
-            "fields": fields or "files(id,name,mimeType,parents)",
-        }
-        try:
-            r = httpx.get(
-                f"{DRIVE_API_BASE}/files",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json().get("files", [])}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def create_drive_folder(
-        self,
-        name: str,
-        parent_folder_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Create a new folder in Google Drive."""
-        payload: Dict[str, Any] = {
-            "name": name,
-            "mimeType": "application/vnd.google-apps.folder",
-        }
-        if parent_folder_id:
-            payload["parents"] = [parent_folder_id]
-        try:
-            r = httpx.post(
-                f"{DRIVE_API_BASE}/files",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_drive_file(
-        self,
-        file_id: str,
-        fields: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Get metadata for a single Drive file."""
-        params = {"fields": fields or "id,parents"}
-        try:
-            r = httpx.get(
-                f"{DRIVE_API_BASE}/files/{file_id}",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def move_drive_file(
-        self,
-        file_id: str,
-        add_parents: str,
-        remove_parents: str,
-    ) -> Dict[str, Any]:
-        """Move a Drive file between folders."""
-        params: Dict[str, str] = {
-            "addParents": add_parents,
-            "fields": "id,parents",
-        }
-        if remove_parents:
-            params["removeParents"] = remove_parents
-        try:
-            r = httpx.patch(
-                f"{DRIVE_API_BASE}/files/{file_id}",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def find_drive_folder_by_name(
-        self,
-        name: str,
-        parent_folder_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Find a Drive folder by name (optionally scoped to a parent)."""
-        q_parts = [
-            f"name = '{name}'",
-            "mimeType = 'application/vnd.google-apps.folder'",
-            "trashed = false",
-        ]
-        if parent_folder_id:
-            q_parts.append(f"'{parent_folder_id}' in parents")
-        params = {
-            "q": " and ".join(q_parts),
-            "fields": "files(id,name)",
-        }
-        try:
-            r = httpx.get(
-                f"{DRIVE_API_BASE}/files",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                files = r.json().get("files", [])
-                folder = files[0] if files else None
-                return {"ok": True, "result": folder}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
diff --git a/app/external_comms/platforms/jira.py b/app/external_comms/platforms/jira.py
deleted file mode 100644
index ac1cffef..00000000
--- a/app/external_comms/platforms/jira.py
+++ /dev/null
@@ -1,1007 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Jira Cloud REST API client — direct HTTP via httpx.
-
-Supports two auth modes:
-- **API Token**: email + API token (Atlassian account).
-- **OAuth 2.0**: access_token + cloud_id (from CraftOS backend OAuth flow).
-
-Listening is implemented via polling the Jira search API (JQL) for
-recently-updated issues. An optional **watch_labels** filter lets
-users restrict events to issues carrying specific labels.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import time
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional, Union
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-JIRA_CLOUD_API = "https://api.atlassian.com/ex/jira"
-CREDENTIAL_FILE = "jira.json"
-
-POLL_INTERVAL = 10      # seconds between polls
-RETRY_DELAY = 15        # seconds to wait after a poll error
-
-
-@dataclass
-class JiraCredential:
-    # API-token auth
-    domain: str = ""            # e.g. "mycompany.atlassian.net"
-    email: str = ""
-    api_token: str = ""
-    # OAuth auth (from CraftOS backend)
-    cloud_id: str = ""
-    access_token: str = ""
-    refresh_token: str = ""
-    token_expiry: float = 0.0
-    site_url: str = ""
-    # Listener settings
-    watch_labels: List[str] = field(default_factory=list)
-    watch_tag: str = ""  # e.g. "@craftbot" — only trigger on comments containing this tag
-
-
-@register_client
-class JiraClient(BasePlatformClient):
-    """Jira Cloud platform client with JQL-based polling listener."""
-
-    PLATFORM_ID = "jira"
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cred: Optional[JiraCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._last_poll_time: Optional[str] = None  # ISO 8601
-        self._seen_issue_keys: set = set()
-        self._catchup_done: bool = False
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> JiraCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, JiraCredential)
-        if self._cred is None:
-            raise RuntimeError("No Jira credentials. Use /jira login first.")
-        return self._cred
-
-    def _is_oauth(self) -> bool:
-        cred = self._load()
-        return bool(cred.cloud_id and cred.access_token)
-
-    def _base_url(self) -> str:
-        cred = self._load()
-        if cred.cloud_id:
-            return f"{JIRA_CLOUD_API}/{cred.cloud_id}/rest/api/3"
-        if cred.domain:
-            domain = cred.domain.rstrip("/")
-            if not domain.startswith("http"):
-                domain = f"https://{domain}"
-            return f"{domain}/rest/api/3"
-        raise RuntimeError("No Jira domain or cloud_id configured.")
-
-    def _headers(self) -> Dict[str, str]:
-        cred = self._load()
-        headers: Dict[str, str] = {
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-        }
-        if cred.cloud_id and cred.access_token:
-            headers["Authorization"] = f"Bearer {cred.access_token}"
-        elif cred.email and cred.api_token:
-            import base64
-            raw = f"{cred.email}:{cred.api_token}"
-            encoded = base64.b64encode(raw.encode()).decode()
-            headers["Authorization"] = f"Basic {encoded}"
-        else:
-            raise RuntimeError("Incomplete Jira credentials (need email+api_token or cloud_id+access_token).")
-        return headers
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a comment to a Jira issue.
-
-        Args:
-            recipient: Issue key (e.g. "PROJ-123").
-            text: Comment body text.
-        """
-        return await self.add_comment(recipient, text)
-
-    # ------------------------------------------------------------------
-    # Watch-label configuration
-    # ------------------------------------------------------------------
-
-    def get_watch_labels(self) -> List[str]:
-        """Return the list of labels the listener filters on."""
-        cred = self._load()
-        return list(cred.watch_labels)
-
-    def set_watch_labels(self, labels: List[str]) -> None:
-        """Set the labels to filter on when listening.
-
-        Pass an empty list to watch all issues (no filtering).
-        """
-        cred = self._load()
-        cred.watch_labels = [lbl.strip() for lbl in labels if lbl.strip()]
-        save_credential(CREDENTIAL_FILE, cred)
-        self._cred = cred
-        logger.info(f"[JIRA] Watch labels set to: {cred.watch_labels or '(all issues)'}")
-
-    def add_watch_label(self, label: str) -> None:
-        """Add a single label to the watch list."""
-        cred = self._load()
-        label = label.strip()
-        if label and label not in cred.watch_labels:
-            cred.watch_labels.append(label)
-            save_credential(CREDENTIAL_FILE, cred)
-            self._cred = cred
-            logger.info(f"[JIRA] Added watch label: {label}")
-
-    def remove_watch_label(self, label: str) -> None:
-        """Remove a single label from the watch list."""
-        cred = self._load()
-        label = label.strip()
-        if label in cred.watch_labels:
-            cred.watch_labels.remove(label)
-            save_credential(CREDENTIAL_FILE, cred)
-            self._cred = cred
-            logger.info(f"[JIRA] Removed watch label: {label}")
-
-    # -- Watch tag (comment mention filter) ----------------------------
-
-    def get_watch_tag(self) -> str:
-        """Return the tag the listener filters comments on (e.g. '@craftbot')."""
-        cred = self._load()
-        return cred.watch_tag
-
-    def set_watch_tag(self, tag: str) -> None:
-        """Set the mention tag to watch for in comments.
-
-        Only comments containing this tag will trigger events.
-        Pass an empty string to trigger on all issue updates (no comment filtering).
-        """
-        cred = self._load()
-        cred.watch_tag = tag.strip()
-        save_credential(CREDENTIAL_FILE, cred)
-        self._cred = cred
-        logger.info(f"[JIRA] Watch tag set to: {cred.watch_tag or '(disabled — all updates)'}")
-
-    # ------------------------------------------------------------------
-    # Listening (JQL polling)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        self._load()
-
-        # Verify credentials
-        me = await self.get_myself()
-        if "error" in me:
-            raise RuntimeError(f"Invalid Jira credentials: {me.get('error')}")
-
-        display = me.get("result", {}).get("displayName", "unknown")
-        logger.info(f"[JIRA] Authenticated as: {display}")
-
-        # Catchup: set last poll time to now
-        self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
-        self._catchup_done = True
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-
-        cred = self._load()
-        labels_info = ", ".join(cred.watch_labels) if cred.watch_labels else "(all)"
-        tag_info = cred.watch_tag or "(disabled — all updates)"
-        logger.info(f"[JIRA] Poller started — labels: {labels_info} | tag: {tag_info}")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[JIRA] Poller stopped")
-
-    async def _poll_loop(self) -> None:
-        while self._listening:
-            try:
-                await self._check_updates()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[JIRA] Poll error: {e}")
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _check_updates(self) -> None:
-        if not self._last_poll_time:
-            return
-
-        cred = self._load()
-
-        # Build JQL
-        jql_parts = [f'updated >= "{self._last_poll_time}"']
-        if cred.watch_labels:
-            label_clauses = " OR ".join(f'labels = "{lbl}"' for lbl in cred.watch_labels)
-            jql_parts.append(f"({label_clauses})")
-        jql = " AND ".join(jql_parts)
-        jql += " ORDER BY updated ASC"
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.post(
-                f"{self._base_url()}/search/jql",
-                headers=self._headers(),
-                json={
-                    "jql": jql,
-                    "maxResults": 50,
-                    "fields": ["summary", "status", "assignee", "reporter", "labels", "updated", "comment", "issuetype", "priority", "project"],
-                },
-                timeout=30,
-            )
-
-            if resp.status_code == 401:
-                logger.warning("[JIRA] Authentication expired (401)")
-                return
-            if resp.status_code != 200:
-                logger.warning(f"[JIRA] Search API error: {resp.status_code} — {resp.text[:300]}")
-                return
-
-            data = resp.json()
-            issues = data.get("issues", [])
-
-            for issue in issues:
-                issue_key = issue.get("key", "")
-                updated = issue.get("fields", {}).get("updated", "")
-
-                # Build a dedup key from issue key + updated timestamp
-                dedup_key = f"{issue_key}:{updated}"
-                if dedup_key in self._seen_issue_keys:
-                    continue
-                self._seen_issue_keys.add(dedup_key)
-
-                await self._dispatch_issue(issue)
-
-            # Update poll time
-            self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
-
-            # Cap seen set
-            if len(self._seen_issue_keys) > 500:
-                self._seen_issue_keys = set(list(self._seen_issue_keys)[-200:])
-
-    async def _dispatch_issue(self, issue: Dict[str, Any]) -> None:
-        if not self._message_callback:
-            return
-
-        cred = self._load()
-        fields_data = issue.get("fields", {})
-        issue_key = issue.get("key", "")
-        summary = fields_data.get("summary", "")
-        status_name = (fields_data.get("status") or {}).get("name", "")
-        issue_type = (fields_data.get("issuetype") or {}).get("name", "")
-        priority = (fields_data.get("priority") or {}).get("name", "")
-        project_key = (fields_data.get("project") or {}).get("key", "")
-        labels = fields_data.get("labels", [])
-
-        assignee = fields_data.get("assignee") or {}
-        assignee_name = assignee.get("displayName", "Unassigned")
-
-        reporter = fields_data.get("reporter") or {}
-        reporter_name = reporter.get("displayName", "Unknown")
-
-        # Extract comments
-        comments = (fields_data.get("comment") or {}).get("comments", [])
-
-        # --- Watch tag filtering ---
-        # If a watch_tag is set, only dispatch when a comment contains the tag.
-        # The triggering comment text (after the tag) becomes the message.
-        watch_tag = cred.watch_tag
-        if watch_tag:
-            matching_comment = None
-            tag_lower = watch_tag.lower()
-            # Scan comments newest-first for one containing the tag
-            for comment in reversed(comments):
-                comment_body = _extract_adf_text(comment.get("body", {}))
-                if tag_lower in comment_body.lower():
-                    # Dedup: use comment ID so we don't re-trigger on same comment
-                    comment_id = comment.get("id", "")
-                    comment_dedup = f"{issue_key}:comment:{comment_id}"
-                    if comment_dedup in self._seen_issue_keys:
-                        continue
-                    self._seen_issue_keys.add(comment_dedup)
-                    matching_comment = comment
-                    break
-
-            if matching_comment is None:
-                # No comment with the tag — skip this issue entirely
-                return
-
-            # Build message from the tagged comment
-            comment_author = (matching_comment.get("author") or {}).get("displayName", "Unknown")
-            comment_author_id = (matching_comment.get("author") or {}).get("accountId", "")
-            comment_body = _extract_adf_text(matching_comment.get("body", {}))
-
-            # Strip the tag from the comment to get the instruction
-            idx = comment_body.lower().find(tag_lower)
-            if idx >= 0:
-                instruction = comment_body[idx + len(watch_tag):].strip()
-            else:
-                instruction = comment_body
-
-            text_parts = [
-                f"[{issue_key}] {summary}",
-                f"Status: {status_name} | Assignee: {assignee_name}",
-                f"Comment by {comment_author}: {instruction or comment_body}",
-            ]
-
-            timestamp = None
-            created_str = matching_comment.get("created", "")
-            if created_str:
-                try:
-                    timestamp = datetime.fromisoformat(created_str.replace("Z", "+00:00"))
-                except Exception:
-                    pass
-
-            platform_msg = PlatformMessage(
-                platform="jira",
-                sender_id=comment_author_id,
-                sender_name=comment_author,
-                text="\n".join(text_parts),
-                channel_id=project_key,
-                channel_name=f"{project_key} ({issue_type})",
-                message_id=f"{issue_key}:{matching_comment.get('id', '')}",
-                timestamp=timestamp,
-                raw={
-                    "issue": issue,
-                    "trigger": "comment_tag",
-                    "tag": watch_tag,
-                    "instruction": instruction or comment_body,
-                    "comment": matching_comment,
-                },
-            )
-
-            await self._message_callback(platform_msg)
-            logger.info(f"[JIRA] Tag '{watch_tag}' matched in {issue_key} by {comment_author}: {instruction[:80]}...")
-            return
-
-        # --- No watch tag — dispatch all updates (original behavior) ---
-        text_parts = [
-            f"[{issue_key}] {summary}",
-            f"Type: {issue_type} | Priority: {priority} | Status: {status_name}",
-            f"Project: {project_key} | Assignee: {assignee_name}",
-        ]
-        if labels:
-            text_parts.append(f"Labels: {', '.join(labels)}")
-
-        if comments:
-            latest_comment = comments[-1]
-            comment_author = (latest_comment.get("author") or {}).get("displayName", "")
-            comment_body = _extract_adf_text(latest_comment.get("body", {}))
-            if comment_body:
-                text_parts.append(f"Latest comment by {comment_author}: {comment_body[:200]}")
-
-        timestamp = None
-        updated_str = fields_data.get("updated", "")
-        if updated_str:
-            try:
-                timestamp = datetime.fromisoformat(updated_str.replace("Z", "+00:00"))
-            except Exception:
-                pass
-
-        platform_msg = PlatformMessage(
-            platform="jira",
-            sender_id=reporter.get("accountId", ""),
-            sender_name=reporter_name,
-            text="\n".join(text_parts),
-            channel_id=project_key,
-            channel_name=f"{project_key} ({issue_type})",
-            message_id=issue_key,
-            timestamp=timestamp,
-            raw=issue,
-        )
-
-        await self._message_callback(platform_msg)
-
-    # ------------------------------------------------------------------
-    # Jira REST API methods
-    # ------------------------------------------------------------------
-
-    async def get_myself(self) -> Dict[str, Any]:
-        """Get the authenticated user's info."""
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/myself",
-                    headers=self._headers(),
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    return {
-                        "ok": True,
-                        "result": {
-                            "accountId": data.get("accountId"),
-                            "displayName": data.get("displayName"),
-                            "emailAddress": data.get("emailAddress", ""),
-                            "active": data.get("active", True),
-                        },
-                    }
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def search_issues(
-        self,
-        jql: str,
-        max_results: int = 50,
-        fields_list: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """Search for issues using JQL.
-
-        Args:
-            jql: JQL query string.
-            max_results: Maximum number of results (max 100).
-            fields_list: List of fields to return.
-
-        Returns:
-            API response with matching issues or error.
-        """
-        payload: Dict[str, Any] = {
-            "jql": jql,
-            "maxResults": min(max_results, 100),
-        }
-        if fields_list:
-            payload["fields"] = fields_list
-
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{self._base_url()}/search/jql",
-                    headers=self._headers(),
-                    json=payload,
-                    timeout=30,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    return {
-                        "ok": True,
-                        "result": {
-                            "total": data.get("total", 0),
-                            "issues": data.get("issues", []),
-                        },
-                    }
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_issue(
-        self,
-        issue_key: str,
-        fields_list: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """Get a single issue by key.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            fields_list: Optional list of fields to return.
-
-        Returns:
-            API response with issue data or error.
-        """
-        params: Dict[str, Any] = {}
-        if fields_list:
-            params["fields"] = ",".join(fields_list)
-
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/issue/{issue_key}",
-                    headers=self._headers(),
-                    params=params,
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def create_issue(
-        self,
-        project_key: str,
-        summary: str,
-        issue_type: str = "Task",
-        description: Optional[str] = None,
-        assignee_id: Optional[str] = None,
-        labels: Optional[List[str]] = None,
-        priority: Optional[str] = None,
-        extra_fields: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Create a new issue.
-
-        Args:
-            project_key: Project key (e.g. "PROJ").
-            summary: Issue summary/title.
-            issue_type: Issue type name (e.g. "Task", "Bug", "Story").
-            description: Optional plain-text description (converted to ADF).
-            assignee_id: Optional Atlassian account ID.
-            labels: Optional list of label strings.
-            priority: Optional priority name (e.g. "High").
-            extra_fields: Optional additional fields dict.
-
-        Returns:
-            API response with created issue key/id or error.
-        """
-        fields_payload: Dict[str, Any] = {
-            "project": {"key": project_key},
-            "summary": summary,
-            "issuetype": {"name": issue_type},
-        }
-
-        if description:
-            fields_payload["description"] = _text_to_adf(description)
-        if assignee_id:
-            fields_payload["assignee"] = {"accountId": assignee_id}
-        if labels:
-            fields_payload["labels"] = labels
-        if priority:
-            fields_payload["priority"] = {"name": priority}
-        if extra_fields:
-            fields_payload.update(extra_fields)
-
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{self._base_url()}/issue",
-                    headers=self._headers(),
-                    json={"fields": fields_payload},
-                    timeout=15,
-                )
-                if resp.status_code in (200, 201):
-                    data = resp.json()
-                    return {
-                        "ok": True,
-                        "result": {
-                            "id": data.get("id"),
-                            "key": data.get("key"),
-                            "self": data.get("self"),
-                        },
-                    }
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def update_issue(
-        self,
-        issue_key: str,
-        fields_update: Dict[str, Any],
-    ) -> Dict[str, Any]:
-        """Update an existing issue's fields.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            fields_update: Dict of field names to new values.
-
-        Returns:
-            API response or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.put(
-                    f"{self._base_url()}/issue/{issue_key}",
-                    headers=self._headers(),
-                    json={"fields": fields_update},
-                    timeout=15,
-                )
-                if resp.status_code == 204:
-                    return {"ok": True, "result": {"updated": True, "key": issue_key}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def add_comment(
-        self,
-        issue_key: str,
-        body: str,
-    ) -> Dict[str, Any]:
-        """Add a comment to an issue.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            body: Comment body text (converted to ADF).
-
-        Returns:
-            API response with comment details or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{self._base_url()}/issue/{issue_key}/comment",
-                    headers=self._headers(),
-                    json={"body": _text_to_adf(body)},
-                    timeout=15,
-                )
-                if resp.status_code in (200, 201):
-                    data = resp.json()
-                    return {
-                        "ok": True,
-                        "result": {
-                            "id": data.get("id"),
-                            "created": data.get("created"),
-                            "author": (data.get("author") or {}).get("displayName", ""),
-                        },
-                    }
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_transitions(self, issue_key: str) -> Dict[str, Any]:
-        """Get available status transitions for an issue.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-
-        Returns:
-            API response with list of transitions or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/issue/{issue_key}/transitions",
-                    headers=self._headers(),
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    transitions = [
-                        {
-                            "id": t.get("id"),
-                            "name": t.get("name"),
-                            "to": (t.get("to") or {}).get("name", ""),
-                        }
-                        for t in data.get("transitions", [])
-                    ]
-                    return {"ok": True, "result": {"transitions": transitions}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def transition_issue(
-        self,
-        issue_key: str,
-        transition_id: str,
-        comment: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Transition an issue to a new status.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            transition_id: Transition ID (from get_transitions).
-            comment: Optional comment to add with the transition.
-
-        Returns:
-            API response or error.
-        """
-        payload: Dict[str, Any] = {
-            "transition": {"id": transition_id},
-        }
-        if comment:
-            payload["update"] = {
-                "comment": [{"add": {"body": _text_to_adf(comment)}}],
-            }
-
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(
-                    f"{self._base_url()}/issue/{issue_key}/transitions",
-                    headers=self._headers(),
-                    json=payload,
-                    timeout=15,
-                )
-                if resp.status_code == 204:
-                    return {"ok": True, "result": {"transitioned": True, "key": issue_key}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def assign_issue(
-        self,
-        issue_key: str,
-        account_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Assign an issue to a user (or unassign with None).
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            account_id: Atlassian account ID, or None to unassign.
-
-        Returns:
-            API response or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.put(
-                    f"{self._base_url()}/issue/{issue_key}/assignee",
-                    headers=self._headers(),
-                    json={"accountId": account_id},
-                    timeout=15,
-                )
-                if resp.status_code == 204:
-                    return {"ok": True, "result": {"assigned": True, "key": issue_key}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_projects(self, max_results: int = 50) -> Dict[str, Any]:
-        """Get list of accessible projects.
-
-        Args:
-            max_results: Maximum number of projects to return.
-
-        Returns:
-            API response with projects list or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/project/search",
-                    headers=self._headers(),
-                    params={"maxResults": max_results},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    projects = [
-                        {
-                            "id": p.get("id"),
-                            "key": p.get("key"),
-                            "name": p.get("name"),
-                            "style": p.get("style", ""),
-                        }
-                        for p in data.get("values", [])
-                    ]
-                    return {"ok": True, "result": {"projects": projects}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def search_users(
-        self,
-        query: str,
-        max_results: int = 20,
-    ) -> Dict[str, Any]:
-        """Search for Jira users.
-
-        Args:
-            query: Search string (name or email).
-            max_results: Maximum results to return.
-
-        Returns:
-            API response with matching users or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/user/search",
-                    headers=self._headers(),
-                    params={"query": query, "maxResults": max_results},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    users = [
-                        {
-                            "accountId": u.get("accountId"),
-                            "displayName": u.get("displayName"),
-                            "emailAddress": u.get("emailAddress", ""),
-                            "active": u.get("active", True),
-                        }
-                        for u in resp.json()
-                    ]
-                    return {"ok": True, "result": {"users": users}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_issue_comments(
-        self,
-        issue_key: str,
-        max_results: int = 50,
-    ) -> Dict[str, Any]:
-        """Get comments on an issue.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            max_results: Maximum comments to return.
-
-        Returns:
-            API response with comments or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/issue/{issue_key}/comment",
-                    headers=self._headers(),
-                    params={"maxResults": max_results, "orderBy": "-created"},
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    data = resp.json()
-                    comments = [
-                        {
-                            "id": c.get("id"),
-                            "author": (c.get("author") or {}).get("displayName", ""),
-                            "body": _extract_adf_text(c.get("body", {})),
-                            "created": c.get("created"),
-                            "updated": c.get("updated"),
-                        }
-                        for c in data.get("comments", [])
-                    ]
-                    return {"ok": True, "result": {"comments": comments, "total": data.get("total", 0)}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_statuses(self, project_key: str) -> Dict[str, Any]:
-        """Get all statuses for a project.
-
-        Args:
-            project_key: Project key (e.g. "PROJ").
-
-        Returns:
-            API response with statuses or error.
-        """
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(
-                    f"{self._base_url()}/project/{project_key}/statuses",
-                    headers=self._headers(),
-                    timeout=15,
-                )
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def add_labels(
-        self,
-        issue_key: str,
-        labels: List[str],
-    ) -> Dict[str, Any]:
-        """Add labels to an issue (without removing existing ones).
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            labels: List of label strings to add.
-
-        Returns:
-            API response or error.
-        """
-        update_payload = {
-            "update": {
-                "labels": [{"add": label} for label in labels],
-            },
-        }
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.put(
-                    f"{self._base_url()}/issue/{issue_key}",
-                    headers=self._headers(),
-                    json=update_payload,
-                    timeout=15,
-                )
-                if resp.status_code == 204:
-                    return {"ok": True, "result": {"labels_added": labels, "key": issue_key}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def remove_labels(
-        self,
-        issue_key: str,
-        labels: List[str],
-    ) -> Dict[str, Any]:
-        """Remove labels from an issue.
-
-        Args:
-            issue_key: Issue key (e.g. "PROJ-123").
-            labels: List of label strings to remove.
-
-        Returns:
-            API response or error.
-        """
-        update_payload = {
-            "update": {
-                "labels": [{"remove": label} for label in labels],
-            },
-        }
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.put(
-                    f"{self._base_url()}/issue/{issue_key}",
-                    headers=self._headers(),
-                    json=update_payload,
-                    timeout=15,
-                )
-                if resp.status_code == 204:
-                    return {"ok": True, "result": {"labels_removed": labels, "key": issue_key}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-
-# ------------------------------------------------------------------
-# ADF (Atlassian Document Format) helpers
-# ------------------------------------------------------------------
-
-def _text_to_adf(text: str) -> Dict[str, Any]:
-    """Convert plain text to Atlassian Document Format (ADF)."""
-    paragraphs = text.split("\n")
-    content = []
-    for para in paragraphs:
-        content.append({
-            "type": "paragraph",
-            "content": [{"type": "text", "text": para}] if para else [],
-        })
-    return {
-        "version": 1,
-        "type": "doc",
-        "content": content,
-    }
-
-
-def _extract_adf_text(adf: Dict[str, Any]) -> str:
-    """Extract plain text from an ADF document."""
-    if not isinstance(adf, dict):
-        return str(adf) if adf else ""
-
-    parts: List[str] = []
-
-    def _walk(node: Any) -> None:
-        if isinstance(node, dict):
-            if node.get("type") == "text":
-                parts.append(node.get("text", ""))
-            for child in node.get("content", []):
-                _walk(child)
-        elif isinstance(node, list):
-            for item in node:
-                _walk(item)
-
-    _walk(adf)
-    return " ".join(parts)
diff --git a/app/external_comms/platforms/linkedin.py b/app/external_comms/platforms/linkedin.py
deleted file mode 100644
index 865f2517..00000000
--- a/app/external_comms/platforms/linkedin.py
+++ /dev/null
@@ -1,1131 +0,0 @@
-# -*- coding: utf-8 -*-
-"""LinkedIn REST API v2 client — direct HTTP via httpx."""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
-from urllib.parse import quote
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-LINKEDIN_API_BASE = "https://api.linkedin.com/v2"
-LINKEDIN_OAUTH_BASE = "https://www.linkedin.com/oauth/v2"
-CREDENTIAL_FILE = "linkedin.json"
-
-
-@dataclass
-class LinkedInCredential:
-    access_token: str = ""
-    refresh_token: str = ""
-    token_expiry: float = 0.0
-    client_id: str = ""
-    client_secret: str = ""
-    linkedin_id: str = ""
-    user_id: str = ""
-
-
-def _encode_urn(urn: str) -> str:
-    """URL-encode a LinkedIn URN for use in API paths."""
-    return quote(urn, safe="")
-
-
-@register_client
-class LinkedInClient(BasePlatformClient):
-    PLATFORM_ID = "linkedin"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[LinkedInCredential] = None
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> LinkedInCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, LinkedInCredential)
-        if self._cred is None:
-            raise RuntimeError("No LinkedIn credentials. Use /linkedin login first.")
-        return self._cred
-
-    def _ensure_token(self) -> str:
-        """Return a valid access token, refreshing if expired."""
-        cred = self._load()
-        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
-            result = self.refresh_access_token()
-            if result:
-                return result
-        return cred.access_token
-
-    def _headers(self) -> Dict[str, str]:
-        return {
-            "Authorization": f"Bearer {self._ensure_token()}",
-            "Content-Type": "application/json",
-            "X-Restli-Protocol-Version": "2.0.0",
-            "LinkedIn-Version": "202401",
-        }
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a LinkedIn message. Wraps send_message_to_recipients for the base interface."""
-        cred = self._load()
-        sender_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else ""
-        return self.send_message_to_recipients(
-            sender_urn=sender_urn,
-            recipient_urns=[recipient],
-            subject=kwargs.get("subject", ""),
-            body=text,
-        )
-
-    # ------------------------------------------------------------------
-    # Token management
-    # ------------------------------------------------------------------
-
-    def refresh_access_token(self) -> Optional[str]:
-        """
-        Refresh the LinkedIn OAuth access token.
-
-        Returns:
-            New access token string if successful, None otherwise.
-        """
-        cred = self._load()
-        if not all([cred.client_id, cred.client_secret, cred.refresh_token]):
-            return None
-
-        payload = {
-            "grant_type": "refresh_token",
-            "refresh_token": cred.refresh_token,
-            "client_id": cred.client_id,
-            "client_secret": cred.client_secret,
-        }
-
-        try:
-            r = httpx.post(
-                f"{LINKEDIN_OAUTH_BASE}/accessToken",
-                data=payload,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                data = r.json()
-                cred.access_token = data["access_token"]
-                expires_in = data.get("expires_in", 5184000)  # Default 60 days
-                # Subtract 24 hours as safety buffer
-                cred.token_expiry = time.time() + expires_in - 86400
-                save_credential(CREDENTIAL_FILE, cred)
-                self._cred = cred
-                return cred.access_token
-        except Exception:
-            pass
-        return None
-
-    # ------------------------------------------------------------------
-    # Profile operations
-    # ------------------------------------------------------------------
-
-    def get_user_profile(self) -> Dict[str, Any]:
-        """
-        Get the authenticated user's profile information.
-        Uses /userinfo endpoint for basic profile data.
-        """
-        headers = {"Authorization": f"Bearer {self._ensure_token()}"}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/userinfo", headers=headers, timeout=15)
-            if r.status_code == 200:
-                data = r.json()
-                return {
-                    "ok": True,
-                    "result": {
-                        "linkedin_id": data.get("sub"),
-                        "name": data.get("name"),
-                        "given_name": data.get("given_name"),
-                        "family_name": data.get("family_name"),
-                        "email": data.get("email"),
-                        "picture": data.get("picture"),
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_profile_details(self) -> Dict[str, Any]:
-        """
-        Get detailed profile information including headline.
-        Uses the /me endpoint.
-        """
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/me", headers=self._headers(), timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Connections / Network
-    # ------------------------------------------------------------------
-
-    def get_connections(self, count: int = 50, start: int = 0) -> Dict[str, Any]:
-        """
-        Get the authenticated user's connections.
-        Note: Access to connections is limited in LinkedIn API v2.
-        """
-        params = {"q": "viewer", "count": min(count, 50), "start": start}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/connections", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Search
-    # ------------------------------------------------------------------
-
-    def search_people(self, keywords: str, count: int = 25, start: int = 0) -> Dict[str, Any]:
-        """
-        Search for people on LinkedIn.
-        Note: People search API may require special permissions.
-        """
-        params = {"q": "search", "keywords": keywords, "count": min(count, 50), "start": start}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/people", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {
-                "error": f"API error: {r.status_code}",
-                "details": r.text,
-                "note": "People search may require specific API access.",
-            }
-        except Exception as e:
-            return {"error": str(e)}
-
-    def search_jobs(
-        self, keywords: str, location: Optional[str] = None, count: int = 25, start: int = 0
-    ) -> Dict[str, Any]:
-        """
-        Search for job postings on LinkedIn.
-        Note: Job search API access may be limited and require special permissions.
-        """
-        params: Dict[str, Any] = {"keywords": keywords, "count": min(count, 50), "start": start}
-        if location:
-            params["locationGeoUrn"] = location
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/jobSearch", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {
-                "error": f"API error: {r.status_code}",
-                "details": r.text,
-                "note": "LinkedIn Job Search API access may be restricted.",
-            }
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_job_details(self, job_id: str) -> Dict[str, Any]:
-        """Get details about a specific job posting."""
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/jobs/{job_id}", headers=self._headers(), timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def search_companies(self, keywords: str, count: int = 25, start: int = 0) -> Dict[str, Any]:
-        """Search for companies/organizations on LinkedIn."""
-        params = {"q": "vanityName", "vanityName": keywords}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/organizationLookup", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            # Try alternative search endpoint
-            alt_params: Dict[str, Any] = {
-                "q": "search",
-                "keywords": keywords,
-                "count": min(count, 50),
-                "start": start,
-            }
-            alt_r = httpx.get(f"{LINKEDIN_API_BASE}/organizations", headers=self._headers(), params=alt_params, timeout=15)
-            if alt_r.status_code == 200:
-                return {"ok": True, "result": alt_r.json()}
-            return {
-                "error": f"API error: {r.status_code}",
-                "details": r.text,
-                "note": "Organization search may require specific API access.",
-            }
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_company_by_vanity_name(self, vanity_name: str) -> Dict[str, Any]:
-        """
-        Look up a company by its vanity name (URL slug).
-        e.g. "microsoft" from linkedin.com/company/microsoft
-        """
-        params = {"q": "vanityName", "vanityName": vanity_name}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/organizations", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_person(self, person_id: str) -> Dict[str, Any]:
-        """
-        Get a person's profile by their LinkedIn ID.
-
-        Args:
-            person_id: LinkedIn person ID (numeric, not URN).
-        """
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/people/(id:{person_id})", headers=self._headers(), timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Organization / Company operations
-    # ------------------------------------------------------------------
-
-    def get_my_organizations(self) -> Dict[str, Any]:
-        """
-        Get organizations where the authenticated user has admin access.
-        Required for posting as a company page.
-        """
-        params = {
-            "q": "roleAssignee",
-            "role": "ADMINISTRATOR",
-            "projection": "(elements*(organization~,roleAssignee))",
-        }
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/organizationAcls", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_organization(self, organization_id: str) -> Dict[str, Any]:
-        """
-        Get information about a LinkedIn organization/company.
-
-        Args:
-            organization_id: Organization ID (numeric, not URN).
-        """
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/organizations/{organization_id}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_organization_followers_count(self, organization_urn: str) -> Dict[str, Any]:
-        """Get follower statistics for an organization."""
-        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
-        params = {
-            "q": "organizationalEntity",
-            "organizationalEntity": f"urn:li:organization:{org_id}",
-        }
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/organizationalEntityFollowerStatistics",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Post operations
-    # ------------------------------------------------------------------
-
-    def create_text_post(
-        self, author_urn: str, text: str, visibility: str = "PUBLIC"
-    ) -> Dict[str, Any]:
-        """
-        Create a text-only post on LinkedIn.
-
-        Args:
-            author_urn: URN of author (urn:li:person:xxx or urn:li:organization:xxx).
-            text: Post text content (max 3000 characters).
-            visibility: "PUBLIC", "CONNECTIONS", or "LOGGED_IN".
-        """
-        payload = {
-            "author": author_urn,
-            "lifecycleState": "PUBLISHED",
-            "specificContent": {
-                "com.linkedin.ugc.ShareContent": {
-                    "shareCommentary": {"text": text[:3000]},
-                    "shareMediaCategory": "NONE",
-                }
-            },
-            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def create_article_post(
-        self,
-        author_urn: str,
-        text: str,
-        link_url: str,
-        link_title: str = "",
-        link_description: str = "",
-        visibility: str = "PUBLIC",
-    ) -> Dict[str, Any]:
-        """
-        Create a post with a link/article on LinkedIn.
-
-        Args:
-            author_urn: URN of author.
-            text: Post text content (max 3000 characters).
-            link_url: URL to share.
-            link_title: Optional title for the link.
-            link_description: Optional description for the link.
-            visibility: "PUBLIC", "CONNECTIONS", or "LOGGED_IN".
-        """
-        media_item: Dict[str, Any] = {"status": "READY", "originalUrl": link_url}
-        if link_title:
-            media_item["title"] = {"text": link_title}
-        if link_description:
-            media_item["description"] = {"text": link_description}
-
-        payload = {
-            "author": author_urn,
-            "lifecycleState": "PUBLISHED",
-            "specificContent": {
-                "com.linkedin.ugc.ShareContent": {
-                    "shareCommentary": {"text": text[:3000]},
-                    "shareMediaCategory": "ARTICLE",
-                    "media": [media_item],
-                }
-            },
-            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def create_image_post(
-        self,
-        author_urn: str,
-        text: str,
-        image_url: str,
-        image_title: str = "",
-        visibility: str = "PUBLIC",
-    ) -> Dict[str, Any]:
-        """
-        Create a post with an image on LinkedIn.
-        Note: This version supports external image URLs.
-        """
-        payload = {
-            "author": author_urn,
-            "lifecycleState": "PUBLISHED",
-            "specificContent": {
-                "com.linkedin.ugc.ShareContent": {
-                    "shareCommentary": {"text": text[:3000]},
-                    "shareMediaCategory": "IMAGE",
-                    "media": [
-                        {
-                            "status": "READY",
-                            "originalUrl": image_url,
-                            "title": {"text": image_title or ""},
-                        }
-                    ],
-                }
-            },
-            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def reshare_post(
-        self,
-        author_urn: str,
-        original_post_urn: str,
-        commentary: str = "",
-        visibility: str = "PUBLIC",
-    ) -> Dict[str, Any]:
-        """
-        Reshare/repost existing content with optional commentary.
-
-        Args:
-            author_urn: URN of the person resharing.
-            original_post_urn: URN of the original post to reshare.
-            commentary: Optional text to add (max 3000 chars).
-            visibility: "PUBLIC", "CONNECTIONS", or "LOGGED_IN".
-        """
-        payload = {
-            "author": author_urn,
-            "lifecycleState": "PUBLISHED",
-            "specificContent": {
-                "com.linkedin.ugc.ShareContent": {
-                    "shareCommentary": {"text": commentary[:3000] if commentary else ""},
-                    "shareMediaCategory": "ARTICLE",
-                    "media": [
-                        {
-                            "status": "READY",
-                            "originalUrl": f"https://www.linkedin.com/feed/update/{original_post_urn}",
-                        }
-                    ],
-                }
-            },
-            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def delete_post(self, post_urn: str) -> Dict[str, Any]:
-        """
-        Delete a LinkedIn post.
-
-        Args:
-            post_urn: URN of the post (urn:li:share:xxx or urn:li:ugcPost:xxx).
-        """
-        try:
-            r = httpx.delete(
-                f"{LINKEDIN_API_BASE}/ugcPosts/{_encode_urn(post_urn)}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"deleted": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_post(self, post_urn: str) -> Dict[str, Any]:
-        """
-        Get a specific post by URN.
-
-        Args:
-            post_urn: URN of the post (urn:li:share:xxx or urn:li:ugcPost:xxx).
-        """
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/ugcPosts/{_encode_urn(post_urn)}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_posts_by_author(
-        self, author_urn: str, count: int = 50, start: int = 0
-    ) -> Dict[str, Any]:
-        """
-        Get posts authored by a specific user or organization.
-
-        Args:
-            author_urn: URN of the author (urn:li:person:xxx or urn:li:organization:xxx).
-            count: Number of results (max 100).
-            start: Pagination offset.
-        """
-        params = {
-            "q": "authors",
-            "authors": f"List({author_urn})",
-            "count": min(count, 100),
-            "start": start,
-        }
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Messaging
-    # ------------------------------------------------------------------
-
-    def send_message_to_recipients(
-        self,
-        sender_urn: str,
-        recipient_urns: List[str],
-        subject: str,
-        body: str,
-    ) -> Dict[str, Any]:
-        """
-        Send a message to one or more LinkedIn users.
-        Note: Requires specific messaging permissions. Works best with InMail
-        credits or for users you are already connected with.
-
-        Args:
-            sender_urn: URN of the sender (urn:li:person:xxx).
-            recipient_urns: List of recipient URNs.
-            subject: Message subject.
-            body: Message body text.
-        """
-        payload = {
-            "recipients": recipient_urns,
-            "subject": subject,
-            "body": body,
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/messages", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json() if r.text else {"sent": True}}
-            return {
-                "error": f"API error: {r.status_code}",
-                "details": r.text,
-                "note": "Messaging API requires special permissions. You may need to be connected with the recipient.",
-            }
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Connection requests / Invitations
-    # ------------------------------------------------------------------
-
-    def send_connection_request(
-        self, invitee_profile_urn: str, message: Optional[str] = None
-    ) -> Dict[str, Any]:
-        """
-        Send a connection request (invitation) to another LinkedIn user.
-
-        Args:
-            invitee_profile_urn: URN of the person to invite (urn:li:person:xxx).
-            message: Optional personalized message (max 300 characters).
-        """
-        payload: Dict[str, Any] = {"invitee": invitee_profile_urn}
-        if message:
-            payload["message"] = message[:300]
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/invitations", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json() if r.text else {"sent": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def withdraw_connection_request(self, invitation_urn: str) -> Dict[str, Any]:
-        """Withdraw a pending connection request."""
-        try:
-            r = httpx.delete(
-                f"{LINKEDIN_API_BASE}/invitations/{_encode_urn(invitation_urn)}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"withdrawn": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_sent_invitations(self, count: int = 50, start: int = 0) -> Dict[str, Any]:
-        """Get sent connection invitations (pending)."""
-        params = {"q": "inviter", "count": min(count, 50), "start": start}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/invitations", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_received_invitations(self, count: int = 50, start: int = 0) -> Dict[str, Any]:
-        """Get received connection invitations (pending)."""
-        params = {"q": "invitee", "count": min(count, 50), "start": start}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/invitations", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def respond_to_invitation(self, invitation_urn: str, action: str) -> Dict[str, Any]:
-        """
-        Accept or ignore a received connection invitation.
-
-        Args:
-            invitation_urn: URN of the invitation.
-            action: "accept" or "ignore".
-        """
-        payload = {"action": action.upper()}
-        try:
-            r = httpx.patch(
-                f"{LINKEDIN_API_BASE}/invitations/{_encode_urn(invitation_urn)}",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"action": action, "completed": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Conversations
-    # ------------------------------------------------------------------
-
-    def get_conversations(self, count: int = 20, start: int = 0) -> Dict[str, Any]:
-        """
-        Get message conversations.
-        Note: Requires messaging permissions which may be restricted.
-        """
-        params = {"count": min(count, 50), "start": start}
-        try:
-            r = httpx.get(f"{LINKEDIN_API_BASE}/conversations", headers=self._headers(), params=params, timeout=15)
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {
-                "error": f"API error: {r.status_code}",
-                "details": r.text,
-                "note": "Messaging API requires special permissions.",
-            }
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Social actions (likes / reactions)
-    # ------------------------------------------------------------------
-
-    def like_post(self, actor_urn: str, post_urn: str) -> Dict[str, Any]:
-        """
-        Like/react to a LinkedIn post.
-
-        Args:
-            actor_urn: URN of the person liking (urn:li:person:xxx).
-            post_urn: URN of the post to like.
-        """
-        payload = {"actor": actor_urn}
-        try:
-            r = httpx.post(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json() if r.text else {"liked": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def unlike_post(self, actor_urn: str, post_urn: str) -> Dict[str, Any]:
-        """
-        Remove like/reaction from a LinkedIn post.
-
-        Args:
-            actor_urn: URN of the person who liked.
-            post_urn: URN of the post.
-        """
-        composite_key = quote(f"(liker:{actor_urn})", safe="")
-        try:
-            r = httpx.delete(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes/{composite_key}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"unliked": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_post_reactions(self, post_urn: str, count: int = 50, start: int = 0) -> Dict[str, Any]:
-        """
-        Get likes/reactions on a LinkedIn post.
-
-        Args:
-            post_urn: URN of the post.
-            count: Number of results (max 100).
-            start: Pagination offset.
-        """
-        params = {"count": min(count, 100), "start": start}
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Comments
-    # ------------------------------------------------------------------
-
-    def comment_on_post(
-        self,
-        actor_urn: str,
-        post_urn: str,
-        text: str,
-        parent_comment_urn: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """
-        Create a comment on a LinkedIn post.
-
-        Args:
-            actor_urn: URN of the commenter (urn:li:person:xxx).
-            post_urn: URN of the post to comment on.
-            text: Comment text (max 1250 characters).
-            parent_comment_urn: Optional parent comment URN for replies.
-        """
-        payload: Dict[str, Any] = {
-            "actor": actor_urn,
-            "message": {"text": text[:1250]},
-        }
-        if parent_comment_urn:
-            payload["parentComment"] = parent_comment_urn
-        try:
-            r = httpx.post(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_post_comments(self, post_urn: str, count: int = 50, start: int = 0) -> Dict[str, Any]:
-        """
-        Get comments on a LinkedIn post.
-
-        Args:
-            post_urn: URN of the post.
-            count: Number of results (max 100).
-            start: Pagination offset.
-        """
-        params = {"count": min(count, 100), "start": start}
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def delete_comment(self, actor_urn: str, post_urn: str, comment_urn: str) -> Dict[str, Any]:
-        """
-        Delete a comment from a LinkedIn post.
-
-        Args:
-            actor_urn: URN of the person deleting the comment.
-            post_urn: URN of the post.
-            comment_urn: URN of the comment to delete.
-        """
-        params = {"actor": actor_urn}
-        try:
-            r = httpx.delete(
-                f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments/{_encode_urn(comment_urn)}",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"deleted": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Analytics
-    # ------------------------------------------------------------------
-
-    def get_post_analytics(self, share_urns: List[str]) -> Dict[str, Any]:
-        """
-        Get statistics (views, likes, comments, shares) for posts.
-
-        Args:
-            share_urns: List of share/post URNs.
-        """
-        params = {
-            "q": "organizationalEntity",
-            "shares": ",".join(share_urns),
-        }
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/organizationalEntityShareStatistics",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            # Try alternative endpoint for personal posts
-            alt_params = {"ids": f"List({','.join(share_urns)})"}
-            alt_r = httpx.get(
-                f"{LINKEDIN_API_BASE}/socialMetadata",
-                headers=self._headers(),
-                params=alt_params,
-                timeout=15,
-            )
-            if alt_r.status_code == 200:
-                return {"ok": True, "result": alt_r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_social_metadata(self, post_urn: str) -> Dict[str, Any]:
-        """
-        Get social metadata (likes count, comments count, shares count) for a post.
-
-        Args:
-            post_urn: URN of the post.
-        """
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/socialMetadata/{_encode_urn(post_urn)}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_organization_analytics(self, organization_urn: str) -> Dict[str, Any]:
-        """
-        Get page statistics/analytics for an organization.
-        Requires rw_organization_admin scope.
-
-        Args:
-            organization_urn: URN or numeric ID of the organization.
-        """
-        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
-        params = {
-            "q": "organization",
-            "organization": f"urn:li:organization:{org_id}",
-        }
-        try:
-            r = httpx.get(
-                f"{LINKEDIN_API_BASE}/organizationPageStatistics",
-                headers=self._headers(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Follow / Unfollow
-    # ------------------------------------------------------------------
-
-    def follow_organization(self, follower_urn: str, organization_urn: str) -> Dict[str, Any]:
-        """
-        Follow an organization/company page.
-
-        Args:
-            follower_urn: URN of the follower (urn:li:person:xxx).
-            organization_urn: URN of the organization to follow.
-        """
-        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
-        payload = {
-            "followee": f"urn:li:organization:{org_id}",
-            "follower": follower_urn,
-        }
-        try:
-            r = httpx.post(
-                f"{LINKEDIN_API_BASE}/organizationFollows",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json() if r.text else {"following": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def unfollow_organization(self, follower_urn: str, organization_urn: str) -> Dict[str, Any]:
-        """
-        Unfollow an organization/company page.
-
-        Args:
-            follower_urn: URN of the follower.
-            organization_urn: URN of the organization to unfollow.
-        """
-        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
-        followee_urn = f"urn:li:organization:{org_id}"
-        try:
-            r = httpx.delete(
-                f"{LINKEDIN_API_BASE}/organizationFollows/follower={_encode_urn(follower_urn)}&followee={_encode_urn(followee_urn)}",
-                headers=self._headers(),
-                timeout=15,
-            )
-            if r.status_code in (200, 204):
-                return {"ok": True, "result": {"unfollowed": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Media upload
-    # ------------------------------------------------------------------
-
-    def register_image_upload(self, owner_urn: str) -> Dict[str, Any]:
-        """
-        Register an image upload to get an upload URL.
-        First step in uploading images for posts.
-
-        Args:
-            owner_urn: URN of the owner (urn:li:person:xxx or urn:li:organization:xxx).
-        """
-        payload = {
-            "registerUploadRequest": {
-                "recipes": ["urn:li:digitalmediaRecipe:feedshare-image"],
-                "owner": owner_urn,
-                "serviceRelationships": [
-                    {
-                        "relationshipType": "OWNER",
-                        "identifier": "urn:li:userGeneratedContent",
-                    }
-                ],
-            }
-        }
-        try:
-            r = httpx.post(
-                f"{LINKEDIN_API_BASE}/assets?action=registerUpload",
-                headers=self._headers(),
-                json=payload,
-                timeout=15,
-            )
-            if r.status_code in (200, 201):
-                data = r.json()
-                upload_info = data.get("value", {})
-                upload_mechanism = upload_info.get("uploadMechanism", {})
-                media_upload = upload_mechanism.get(
-                    "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest", {}
-                )
-                return {
-                    "ok": True,
-                    "result": {
-                        "upload_url": media_upload.get("uploadUrl"),
-                        "asset": upload_info.get("asset"),
-                        "full_response": data,
-                    },
-                }
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def upload_image_binary(self, upload_url: str, image_data: bytes) -> Dict[str, Any]:
-        """
-        Upload image binary data to LinkedIn.
-        Second step after register_image_upload.
-
-        Args:
-            upload_url: The upload URL from register_image_upload.
-            image_data: Binary image data.
-        """
-        headers = {
-            "Authorization": f"Bearer {self._ensure_token()}",
-            "Content-Type": "application/octet-stream",
-        }
-        try:
-            r = httpx.put(upload_url, headers=headers, content=image_data, timeout=60)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": {"uploaded": True}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def create_post_with_uploaded_image(
-        self,
-        author_urn: str,
-        text: str,
-        asset_urn: str,
-        image_title: str = "",
-        visibility: str = "PUBLIC",
-    ) -> Dict[str, Any]:
-        """
-        Create a post with an uploaded image (using asset URN).
-
-        Args:
-            author_urn: URN of author.
-            text: Post text.
-            asset_urn: Asset URN from the upload process.
-            image_title: Optional image title.
-            visibility: Post visibility.
-        """
-        payload = {
-            "author": author_urn,
-            "lifecycleState": "PUBLISHED",
-            "specificContent": {
-                "com.linkedin.ugc.ShareContent": {
-                    "shareCommentary": {"text": text[:3000]},
-                    "shareMediaCategory": "IMAGE",
-                    "media": [
-                        {
-                            "status": "READY",
-                            "media": asset_urn,
-                            "title": {"text": image_title or ""},
-                        }
-                    ],
-                }
-            },
-            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
-        }
-        try:
-            r = httpx.post(f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(), json=payload, timeout=15)
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": r.json()}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
diff --git a/app/external_comms/platforms/notion.py b/app/external_comms/platforms/notion.py
deleted file mode 100644
index d05974d5..00000000
--- a/app/external_comms/platforms/notion.py
+++ /dev/null
@@ -1,136 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Notion API client — direct HTTP via httpx."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-NOTION_API_BASE = "https://api.notion.com/v1"
-NOTION_VERSION = "2022-06-28"
-CREDENTIAL_FILE = "notion.json"
-
-
-@dataclass
-class NotionCredential:
-    token: str = ""
-
-
-@register_client
-class NotionClient(BasePlatformClient):
-    PLATFORM_ID = "notion"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[NotionCredential] = None
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> NotionCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, NotionCredential)
-        if self._cred is None:
-            raise RuntimeError("No Notion credentials. Use /notion login first.")
-        return self._cred
-
-    def _headers(self) -> Dict[str, str]:
-        cred = self._load()
-        return {
-            "Authorization": f"Bearer {cred.token}",
-            "Content-Type": "application/json",
-            "Notion-Version": NOTION_VERSION,
-        }
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        # Notion doesn't have a messaging concept; no-op
-        return {"ok": False, "error": "Notion does not support messaging"}
-
-    # ------------------------------------------------------------------
-    # API methods
-    # ------------------------------------------------------------------
-
-    def search(self, query: str, filter_type: Optional[str] = None, page_size: int = 100) -> List[Dict[str, Any]]:
-        payload: Dict[str, Any] = {"query": query, "page_size": page_size}
-        if filter_type in ("page", "database"):
-            payload["filter"] = {"property": "object", "value": filter_type}
-        r = httpx.post(f"{NOTION_API_BASE}/search", headers=self._headers(), json=payload)
-        data = r.json()
-        if r.status_code != 200:
-            return [{"error": data}]
-        return data.get("results", [])
-
-    def get_page(self, page_id: str) -> Dict[str, Any]:
-        r = httpx.get(f"{NOTION_API_BASE}/pages/{page_id}", headers=self._headers())
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def get_database(self, database_id: str) -> Dict[str, Any]:
-        r = httpx.get(f"{NOTION_API_BASE}/databases/{database_id}", headers=self._headers())
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def query_database(
-        self,
-        database_id: str,
-        filter_obj: Optional[Dict[str, Any]] = None,
-        sorts: Optional[List[Dict[str, Any]]] = None,
-        page_size: int = 100,
-    ) -> Dict[str, Any]:
-        payload: Dict[str, Any] = {"page_size": page_size}
-        if filter_obj:
-            payload["filter"] = filter_obj
-        if sorts:
-            payload["sorts"] = sorts
-        r = httpx.post(f"{NOTION_API_BASE}/databases/{database_id}/query", headers=self._headers(), json=payload)
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def create_page(
-        self,
-        parent_id: str,
-        parent_type: str,
-        properties: Dict[str, Any],
-        children: Optional[List[Dict[str, Any]]] = None,
-    ) -> Dict[str, Any]:
-        payload: Dict[str, Any] = {"parent": {parent_type: parent_id}, "properties": properties}
-        if children:
-            payload["children"] = children
-        r = httpx.post(f"{NOTION_API_BASE}/pages", headers=self._headers(), json=payload)
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def update_page(self, page_id: str, properties: Dict[str, Any]) -> Dict[str, Any]:
-        r = httpx.patch(f"{NOTION_API_BASE}/pages/{page_id}", headers=self._headers(), json={"properties": properties})
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def get_block_children(self, block_id: str, page_size: int = 100) -> Dict[str, Any]:
-        r = httpx.get(f"{NOTION_API_BASE}/blocks/{block_id}/children", headers=self._headers(), params={"page_size": page_size})
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def append_block_children(self, block_id: str, children: List[Dict[str, Any]]) -> Dict[str, Any]:
-        r = httpx.patch(f"{NOTION_API_BASE}/blocks/{block_id}/children", headers=self._headers(), json={"children": children})
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def delete_block(self, block_id: str) -> Dict[str, Any]:
-        r = httpx.delete(f"{NOTION_API_BASE}/blocks/{block_id}", headers=self._headers())
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
-
-    def get_user(self, user_id: str = "me") -> Dict[str, Any]:
-        r = httpx.get(f"{NOTION_API_BASE}/users/{user_id}", headers=self._headers())
-        data = r.json()
-        return {"error": data} if r.status_code != 200 else data
diff --git a/app/external_comms/platforms/outlook.py b/app/external_comms/platforms/outlook.py
deleted file mode 100644
index 139421df..00000000
--- a/app/external_comms/platforms/outlook.py
+++ /dev/null
@@ -1,434 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Outlook email client — Microsoft Graph API via httpx."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import time
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-GRAPH_API_BASE = "https://graph.microsoft.com/v1.0"
-MS_TOKEN_URL = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
-CREDENTIAL_FILE = "outlook.json"
-
-POLL_INTERVAL = 5       # seconds between inbox polls
-RETRY_DELAY = 10        # seconds to wait after a poll error
-
-
-@dataclass
-class OutlookCredential:
-    access_token: str = ""
-    refresh_token: str = ""
-    token_expiry: float = 0.0
-    client_id: str = ""
-    email: str = ""
-
-
-@register_client
-class OutlookClient(BasePlatformClient):
-    PLATFORM_ID = "outlook"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[OutlookCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._seen_message_ids: set = set()
-        self._last_poll_time: Optional[str] = None  # ISO 8601 timestamp
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> OutlookCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, OutlookCredential)
-        if self._cred is None:
-            raise RuntimeError("No Outlook credentials. Use /outlook login first.")
-        return self._cred
-
-    def _ensure_token(self) -> str:
-        """Return a valid access token, refreshing if expired."""
-        cred = self._load()
-        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
-            result = self.refresh_access_token()
-            if result:
-                return result
-        return cred.access_token
-
-    def refresh_access_token(self) -> Optional[str]:
-        cred = self._load()
-        if not all([cred.client_id, cred.refresh_token]):
-            return None
-        try:
-            r = httpx.post(
-                MS_TOKEN_URL,
-                data={
-                    "client_id": cred.client_id,
-                    "refresh_token": cred.refresh_token,
-                    "grant_type": "refresh_token",
-                    "scope": "Mail.Read Mail.Send Mail.ReadWrite User.Read offline_access",
-                },
-                timeout=15,
-            )
-            if r.status_code == 200:
-                data = r.json()
-                cred.access_token = data["access_token"]
-                # Microsoft may rotate refresh tokens
-                cred.refresh_token = data.get("refresh_token", cred.refresh_token)
-                cred.token_expiry = time.time() + data.get("expires_in", 3600) - 60
-                save_credential(CREDENTIAL_FILE, cred)
-                self._cred = cred
-                return cred.access_token
-        except Exception:
-            pass
-        return None
-
-    def _headers(self) -> Dict[str, str]:
-        return {
-            "Authorization": f"Bearer {self._ensure_token()}",
-            "Content-Type": "application/json",
-        }
-
-    def _auth_header(self) -> Dict[str, str]:
-        return {"Authorization": f"Bearer {self._ensure_token()}"}
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        cred = self._load()
-        if not cred.access_token:
-            raise RuntimeError(
-                "Outlook credentials need to be updated. "
-                "Run /outlook logout then /outlook login to re-authenticate."
-            )
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        subject = kwargs.get("subject", "")
-        return self.send_email(to=recipient, subject=subject, body=text)
-
-    # ------------------------------------------------------------------
-    # Listening support (email polling via Graph API)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        self._load()
-
-        # Verify token works and get user profile
-        try:
-            profile = await self._async_get_profile()
-            email_addr = profile.get("mail") or profile.get("userPrincipalName", "")
-            logger.info(f"[OUTLOOK] Connected as: {email_addr}")
-        except Exception as e:
-            raise RuntimeError(f"Failed to connect to Outlook: {e}")
-
-        # Catchup: set last poll time to now so we don't dispatch old messages
-        self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-        logger.info("[OUTLOOK] Email poller started")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[OUTLOOK] Email poller stopped")
-
-    async def _async_get_profile(self) -> Dict[str, Any]:
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(
-                f"{GRAPH_API_BASE}/me",
-                headers=self._auth_header(),
-                timeout=15,
-            )
-            if resp.status_code != 200:
-                raise RuntimeError(f"Graph /me error: {resp.status_code}")
-            return resp.json()
-
-    async def _poll_loop(self) -> None:
-        logger.info("[OUTLOOK] Catchup complete — watching for new emails")
-
-        while self._listening:
-            try:
-                await self._check_new_messages()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[OUTLOOK] Poll error: {e}")
-                if "401" in str(e):
-                    self.refresh_access_token()
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _check_new_messages(self) -> None:
-        if not self._last_poll_time:
-            return
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(
-                f"{GRAPH_API_BASE}/me/messages",
-                headers=self._auth_header(),
-                params={
-                    "$filter": f"receivedDateTime ge {self._last_poll_time}",
-                    "$orderby": "receivedDateTime asc",
-                    "$top": "50",
-                    "$select": "id,from,subject,bodyPreview,receivedDateTime,conversationId",
-                },
-                timeout=15,
-            )
-            if resp.status_code == 401:
-                self.refresh_access_token()
-                return
-            if resp.status_code != 200:
-                logger.warning(f"[OUTLOOK] messages API error: {resp.status_code}")
-                return
-
-            data = resp.json()
-            messages = data.get("value", [])
-
-            for msg in messages:
-                msg_id = msg.get("id", "")
-                if not msg_id or msg_id in self._seen_message_ids:
-                    continue
-
-                self._seen_message_ids.add(msg_id)
-                await self._dispatch_message(msg)
-
-            # Update last poll time to the most recent message's time
-            if messages:
-                last_received = messages[-1].get("receivedDateTime", "")
-                if last_received:
-                    self._last_poll_time = last_received
-
-            # Cap seen set
-            if len(self._seen_message_ids) > 500:
-                self._seen_message_ids = set(list(self._seen_message_ids)[-200:])
-
-    async def _dispatch_message(self, msg: Dict[str, Any]) -> None:
-        from_obj = msg.get("from", {}).get("emailAddress", {})
-        sender_email = from_obj.get("address", "")
-        sender_name = from_obj.get("name", sender_email)
-
-        # Skip own messages
-        cred = self._load()
-        if sender_email.lower() == (cred.email or "").lower():
-            return
-
-        subject = msg.get("subject", "(no subject)")
-        snippet = msg.get("bodyPreview", "")
-        text = f"Subject: {subject}\n{snippet}" if snippet else f"Subject: {subject}"
-
-        # Parse timestamp
-        timestamp = None
-        dt_str = msg.get("receivedDateTime", "")
-        if dt_str:
-            try:
-                timestamp = datetime.fromisoformat(dt_str.replace("Z", "+00:00"))
-            except Exception:
-                pass
-
-        platform_msg = PlatformMessage(
-            platform="outlook",
-            sender_id=sender_email,
-            sender_name=sender_name,
-            text=text,
-            channel_id=msg.get("conversationId", ""),
-            message_id=msg.get("id", ""),
-            timestamp=timestamp,
-            raw=msg,
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    # ==================================================================
-    # Send Email
-    # ==================================================================
-
-    def send_email(self, to: str, subject: str, body: str, cc: Optional[str] = None,
-                   html: bool = False) -> Dict[str, Any]:
-        """Send email via Microsoft Graph API."""
-        content_type = "HTML" if html else "Text"
-        message: Dict[str, Any] = {
-            "subject": subject,
-            "body": {"contentType": content_type, "content": body},
-            "toRecipients": [{"emailAddress": {"address": to}}],
-        }
-        if cc:
-            message["ccRecipients"] = [
-                {"emailAddress": {"address": addr.strip()}}
-                for addr in cc.split(",")
-            ]
-
-        try:
-            r = httpx.post(
-                f"{GRAPH_API_BASE}/me/sendMail",
-                headers=self._headers(),
-                json={"message": message, "saveToSentItems": True},
-                timeout=15,
-            )
-            if r.status_code == 202:
-                return {"ok": True, "result": {"sent": True, "to": to, "subject": subject}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ==================================================================
-    # Read Emails
-    # ==================================================================
-
-    def list_emails(self, n: int = 10, unread_only: bool = False, folder: str = "inbox") -> Dict[str, Any]:
-        """List recent emails from a folder."""
-        params: Dict[str, Any] = {
-            "$top": n,
-            "$orderby": "receivedDateTime desc",
-            "$select": "id,from,subject,receivedDateTime,isRead,bodyPreview",
-        }
-        if unread_only:
-            params["$filter"] = "isRead eq false"
-
-        try:
-            r = httpx.get(
-                f"{GRAPH_API_BASE}/me/mailFolders/{folder}/messages",
-                headers=self._auth_header(),
-                params=params,
-                timeout=15,
-            )
-            if r.status_code == 200:
-                messages = r.json().get("value", [])
-                emails = []
-                for msg in messages:
-                    from_obj = msg.get("from", {}).get("emailAddress", {})
-                    emails.append({
-                        "id": msg.get("id"),
-                        "from": f"{from_obj.get('name', '')} <{from_obj.get('address', '')}>",
-                        "subject": msg.get("subject", ""),
-                        "date": msg.get("receivedDateTime", ""),
-                        "is_read": msg.get("isRead", False),
-                        "preview": msg.get("bodyPreview", ""),
-                    })
-                return {"ok": True, "result": {"emails": emails, "count": len(emails)}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def get_email(self, message_id: str) -> Dict[str, Any]:
-        """Get full email by ID."""
-        try:
-            r = httpx.get(
-                f"{GRAPH_API_BASE}/me/messages/{message_id}",
-                headers=self._auth_header(),
-                params={"$select": "id,from,toRecipients,subject,body,receivedDateTime,conversationId"},
-                timeout=15,
-            )
-            if r.status_code != 200:
-                return {"error": f"API error: {r.status_code}", "details": r.text}
-
-            msg = r.json()
-            from_obj = msg.get("from", {}).get("emailAddress", {})
-            to_list = [
-                f"{rcpt.get('emailAddress', {}).get('name', '')} <{rcpt.get('emailAddress', {}).get('address', '')}>"
-                for rcpt in msg.get("toRecipients", [])
-            ]
-            return {"ok": True, "result": {
-                "id": msg.get("id"),
-                "from": f"{from_obj.get('name', '')} <{from_obj.get('address', '')}>",
-                "to": ", ".join(to_list),
-                "subject": msg.get("subject", ""),
-                "date": msg.get("receivedDateTime", ""),
-                "body": msg.get("body", {}).get("content", ""),
-            }}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def mark_as_read(self, message_id: str) -> Dict[str, Any]:
-        """Mark email as read."""
-        try:
-            r = httpx.patch(
-                f"{GRAPH_API_BASE}/me/messages/{message_id}",
-                headers=self._headers(),
-                json={"isRead": True},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                return {"ok": True}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def list_folders(self) -> Dict[str, Any]:
-        """List mail folders."""
-        try:
-            r = httpx.get(
-                f"{GRAPH_API_BASE}/me/mailFolders",
-                headers=self._auth_header(),
-                params={"$select": "id,displayName,totalItemCount,unreadItemCount"},
-                timeout=15,
-            )
-            if r.status_code == 200:
-                folders = r.json().get("value", [])
-                return {"ok": True, "result": {"folders": [
-                    {
-                        "id": f.get("id"),
-                        "name": f.get("displayName"),
-                        "total": f.get("totalItemCount"),
-                        "unread": f.get("unreadItemCount"),
-                    }
-                    for f in folders
-                ]}}
-            return {"error": f"API error: {r.status_code}", "details": r.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def read_top_emails(self, n: int = 5, full_body: bool = False) -> Dict[str, Any]:
-        """Read top N emails with details."""
-        listing = self.list_emails(n=n, unread_only=False)
-        if "error" in listing:
-            return listing
-        emails_summary = listing.get("result", {}).get("emails", [])
-        if not full_body:
-            return {"ok": True, "result": emails_summary}
-        detailed = []
-        for e_info in emails_summary:
-            detail = self.get_email(e_info["id"])
-            if "error" not in detail:
-                detailed.append(detail.get("result", detail))
-            else:
-                detailed.append(e_info)
-        return {"ok": True, "result": detailed}
diff --git a/app/external_comms/platforms/slack.py b/app/external_comms/platforms/slack.py
deleted file mode 100644
index efb848ee..00000000
--- a/app/external_comms/platforms/slack.py
+++ /dev/null
@@ -1,593 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Slack API client — direct HTTP via httpx."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-import time
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-SLACK_API_BASE = "https://slack.com/api"
-CREDENTIAL_FILE = "slack.json"
-
-POLL_INTERVAL = 3       # seconds between polls
-RETRY_DELAY = 5         # seconds to wait after a poll error
-
-
-@dataclass
-class SlackCredential:
-    bot_token: str = ""
-    workspace_id: str = ""
-    team_name: str = ""
-
-
-@register_client
-class SlackClient(BasePlatformClient):
-    PLATFORM_ID = "slack"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[SlackCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._bot_user_id: Optional[str] = None
-        self._last_timestamps: Dict[str, str] = {}  # channel_id -> latest ts seen
-        self._catchup_done: bool = False
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> SlackCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, SlackCredential)
-        if self._cred is None:
-            raise RuntimeError("No Slack credentials. Use /slack login first.")
-        return self._cred
-
-    def _headers(self) -> Dict[str, str]:
-        cred = self._load()
-        return {
-            "Authorization": f"Bearer {cred.bot_token}",
-            "Content-Type": "application/json",
-        }
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    # ------------------------------------------------------------------
-    # Listening support (polling via conversations.history)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        cred = self._load()
-
-        # Verify token by calling auth.test
-        async with httpx.AsyncClient() as client:
-            resp = await client.post(
-                f"{SLACK_API_BASE}/auth.test",
-                headers={"Authorization": f"Bearer {cred.bot_token}"},
-            )
-            data = resp.json()
-            if not data.get("ok"):
-                raise RuntimeError(f"Invalid Slack token: {data.get('error', 'unknown')}")
-            self._bot_user_id = data.get("user_id")
-
-        logger.info(f"[SLACK] Bot user ID: {self._bot_user_id}")
-
-        self._listening = True
-        self._catchup_done = False
-        self._poll_task = asyncio.create_task(self._poll_loop())
-        logger.info("[SLACK] Poller started")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[SLACK] Poller stopped")
-
-    async def _poll_loop(self) -> None:
-        """Poll all joined channels for new messages."""
-        # Catchup: record current timestamps for all channels without dispatching
-        logger.info("[SLACK] Running initial catchup...")
-        try:
-            await self._refresh_channel_timestamps()
-            self._catchup_done = True
-            logger.info(f"[SLACK] Catchup complete — tracking {len(self._last_timestamps)} channel(s)")
-        except Exception as e:
-            logger.error(f"[SLACK] Catchup error: {e}")
-            self._catchup_done = True
-
-        while self._listening:
-            try:
-                await self._poll_channels()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[SLACK] Poll error: {e}")
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _get_joined_channels(self) -> List[Dict[str, Any]]:
-        """Get all channels/DMs the bot is a member of."""
-        channels: List[Dict[str, Any]] = []
-        async with httpx.AsyncClient() as client:
-            for ch_type in ("public_channel,private_channel", "mpim,im"):
-                cursor = None
-                while True:
-                    params: Dict[str, Any] = {
-                        "types": ch_type,
-                        "exclude_archived": True,
-                        "limit": 200,
-                    }
-                    if cursor:
-                        params["cursor"] = cursor
-                    resp = await client.get(
-                        f"{SLACK_API_BASE}/conversations.list",
-                        headers=self._headers(),
-                        params=params,
-                    )
-                    data = resp.json()
-                    if not data.get("ok"):
-                        logger.warning(f"[SLACK] conversations.list failed: {data.get('error')}")
-                        break
-                    for ch in data.get("channels", []):
-                        if ch.get("is_member") or ch.get("is_im") or ch.get("is_mpim"):
-                            channels.append(ch)
-                    cursor = data.get("response_metadata", {}).get("next_cursor")
-                    if not cursor:
-                        break
-        return channels
-
-    async def _refresh_channel_timestamps(self) -> None:
-        """Set the 'oldest' timestamp for each channel to now (catchup)."""
-        now_ts = f"{time.time():.6f}"
-        channels = await self._get_joined_channels()
-        for ch in channels:
-            ch_id = ch.get("id", "")
-            if ch_id:
-                self._last_timestamps[ch_id] = now_ts
-
-    async def _poll_channels(self) -> None:
-        """Check all tracked channels for new messages since last poll."""
-        channels = await self._get_joined_channels()
-        # Add any new channels we haven't seen
-        now_ts = f"{time.time():.6f}"
-        for ch in channels:
-            ch_id = ch.get("id", "")
-            if ch_id and ch_id not in self._last_timestamps:
-                self._last_timestamps[ch_id] = now_ts
-
-        async with httpx.AsyncClient() as client:
-            for ch_id, oldest_ts in list(self._last_timestamps.items()):
-                try:
-                    resp = await client.get(
-                        f"{SLACK_API_BASE}/conversations.history",
-                        headers=self._headers(),
-                        params={
-                            "channel": ch_id,
-                            "oldest": oldest_ts,
-                            "limit": 50,
-                        },
-                    )
-                    data = resp.json()
-                    if not data.get("ok"):
-                        if data.get("error") in ("channel_not_found", "not_in_channel"):
-                            self._last_timestamps.pop(ch_id, None)
-                        continue
-
-                    messages = data.get("messages", [])
-                    if not messages:
-                        continue
-
-                    # Messages are newest-first; process oldest-first
-                    messages.sort(key=lambda m: float(m.get("ts", "0")))
-
-                    for msg in messages:
-                        await self._process_message(msg, ch_id)
-
-                    # Advance timestamp past the newest message
-                    newest_ts = messages[-1].get("ts", oldest_ts)
-                    self._last_timestamps[ch_id] = newest_ts
-
-                except Exception as e:
-                    logger.debug(f"[SLACK] Error polling channel {ch_id}: {e}")
-
-    async def _process_message(self, msg: Dict[str, Any], channel_id: str) -> None:
-        """Process a single Slack message and dispatch to callback."""
-        # Skip bot messages (including our own)
-        if msg.get("bot_id"):
-            return
-        # Skip subtypes (joins, leaves, topic changes, etc.)
-        if msg.get("subtype"):
-            return
-
-        user_id = msg.get("user", "")
-        text = msg.get("text", "")
-        if not text:
-            return
-
-        # Skip messages from our own bot user
-        if user_id == self._bot_user_id:
-            return
-
-        # Resolve user name
-        sender_name = user_id
-        try:
-            info = self.get_user_info(user_id)
-            if info.get("ok"):
-                profile = info.get("user", {}).get("profile", {})
-                sender_name = profile.get("display_name") or profile.get("real_name") or user_id
-        except Exception:
-            pass
-
-        ts_float = float(msg.get("ts", "0"))
-        timestamp = datetime.fromtimestamp(ts_float, tz=timezone.utc) if ts_float else None
-
-        platform_msg = PlatformMessage(
-            platform="slack",
-            sender_id=user_id,
-            sender_name=sender_name,
-            text=text,
-            channel_id=channel_id,
-            message_id=msg.get("ts", ""),
-            timestamp=timestamp,
-            raw=msg,
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    # ------------------------------------------------------------------
-    # Send message
-    # ------------------------------------------------------------------
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a message to a Slack channel or DM.
-
-        Args:
-            recipient: Channel ID or user ID for DM.
-            text: Message text.
-            **kwargs: Optional ``thread_ts`` (str) and ``blocks`` (list).
-
-        Returns:
-            API response with message details or error.
-        """
-        thread_ts: Optional[str] = kwargs.get("thread_ts")
-        blocks: Optional[List[Dict[str, Any]]] = kwargs.get("blocks")
-
-        payload: Dict[str, Any] = {
-            "channel": recipient,
-            "text": text,
-        }
-
-        if thread_ts:
-            payload["thread_ts"] = thread_ts
-        if blocks:
-            payload["blocks"] = blocks
-
-        r = httpx.post(f"{SLACK_API_BASE}/chat.postMessage", headers=self._headers(), json=payload)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    # ------------------------------------------------------------------
-    # Channel methods
-    # ------------------------------------------------------------------
-
-    def list_channels(
-        self,
-        types: str = "public_channel,private_channel",
-        limit: int = 100,
-        exclude_archived: bool = True,
-    ) -> Dict[str, Any]:
-        """List channels in the workspace.
-
-        Args:
-            types: Comma-separated channel types (public_channel, private_channel, mpim, im).
-            limit: Maximum number of channels to return.
-            exclude_archived: Whether to exclude archived channels.
-
-        Returns:
-            API response with channels list or error.
-        """
-        params: Dict[str, Any] = {
-            "types": types,
-            "limit": limit,
-            "exclude_archived": exclude_archived,
-        }
-
-        r = httpx.get(f"{SLACK_API_BASE}/conversations.list", headers=self._headers(), params=params)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def get_channel_info(self, channel: str) -> Dict[str, Any]:
-        """Get information about a channel.
-
-        Args:
-            channel: Channel ID.
-
-        Returns:
-            API response with channel info or error.
-        """
-        r = httpx.get(f"{SLACK_API_BASE}/conversations.info", headers=self._headers(), params={"channel": channel})
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def get_channel_history(
-        self,
-        channel: str,
-        limit: int = 100,
-        oldest: Optional[str] = None,
-        latest: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Get message history from a channel.
-
-        Args:
-            channel: Channel ID.
-            limit: Maximum number of messages to return.
-            oldest: Start of time range (Unix timestamp).
-            latest: End of time range (Unix timestamp).
-
-        Returns:
-            API response with messages or error.
-        """
-        params: Dict[str, Any] = {
-            "channel": channel,
-            "limit": limit,
-        }
-
-        if oldest:
-            params["oldest"] = oldest
-        if latest:
-            params["latest"] = latest
-
-        r = httpx.get(f"{SLACK_API_BASE}/conversations.history", headers=self._headers(), params=params)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def create_channel(self, name: str, is_private: bool = False) -> Dict[str, Any]:
-        """Create a new channel.
-
-        Args:
-            name: Channel name (will be lowercased and hyphenated).
-            is_private: Whether the channel should be private.
-
-        Returns:
-            API response with channel info or error.
-        """
-        payload: Dict[str, Any] = {
-            "name": name,
-            "is_private": is_private,
-        }
-
-        r = httpx.post(f"{SLACK_API_BASE}/conversations.create", headers=self._headers(), json=payload)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def invite_to_channel(self, channel: str, users: List[str]) -> Dict[str, Any]:
-        """Invite users to a channel.
-
-        Args:
-            channel: Channel ID.
-            users: List of user IDs to invite.
-
-        Returns:
-            API response or error.
-        """
-        payload: Dict[str, Any] = {
-            "channel": channel,
-            "users": ",".join(users),
-        }
-
-        r = httpx.post(f"{SLACK_API_BASE}/conversations.invite", headers=self._headers(), json=payload)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    # ------------------------------------------------------------------
-    # User methods
-    # ------------------------------------------------------------------
-
-    def list_users(self, limit: int = 100) -> Dict[str, Any]:
-        """List users in the workspace.
-
-        Args:
-            limit: Maximum number of users to return.
-
-        Returns:
-            API response with users list or error.
-        """
-        r = httpx.get(f"{SLACK_API_BASE}/users.list", headers=self._headers(), params={"limit": limit})
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def get_user_info(self, user_id: str) -> Dict[str, Any]:
-        """Get information about a user.
-
-        Args:
-            user_id: The user ID.
-
-        Returns:
-            API response with user info or error.
-        """
-        r = httpx.get(f"{SLACK_API_BASE}/users.info", headers=self._headers(), params={"user": user_id})
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    # ------------------------------------------------------------------
-    # Messaging / DM methods
-    # ------------------------------------------------------------------
-
-    def open_dm(self, users: List[str]) -> Dict[str, Any]:
-        """Open a DM or group DM with users.
-
-        Args:
-            users: List of user IDs (1 for DM, 2+ for group DM).
-
-        Returns:
-            API response with channel info or error.
-        """
-        payload: Dict[str, Any] = {"users": ",".join(users)}
-
-        r = httpx.post(f"{SLACK_API_BASE}/conversations.open", headers=self._headers(), json=payload)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    def search_messages(
-        self,
-        query: str,
-        count: int = 20,
-        sort: str = "timestamp",
-        sort_dir: str = "desc",
-    ) -> Dict[str, Any]:
-        """Search for messages in the workspace.
-
-        Args:
-            query: Search query.
-            count: Number of results to return.
-            sort: Sort by ``"score"`` or ``"timestamp"``.
-            sort_dir: Sort direction ``"asc"`` or ``"desc"``.
-
-        Returns:
-            API response with search results or error.
-        """
-        params: Dict[str, Any] = {
-            "query": query,
-            "count": count,
-            "sort": sort,
-            "sort_dir": sort_dir,
-        }
-
-        r = httpx.get(f"{SLACK_API_BASE}/search.messages", headers=self._headers(), params=params)
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
-
-    # ------------------------------------------------------------------
-    # File methods
-    # ------------------------------------------------------------------
-
-    def upload_file(
-        self,
-        channels: List[str],
-        content: Optional[str] = None,
-        file_path: Optional[str] = None,
-        filename: Optional[str] = None,
-        title: Optional[str] = None,
-        initial_comment: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Upload a file to Slack.
-
-        Args:
-            channels: List of channel IDs to share the file to.
-            content: File content as string (for text files).
-            file_path: Path to local file to upload.
-            filename: Filename to use.
-            title: Title for the file.
-            initial_comment: Message to include with the file.
-
-        Returns:
-            API response with file info or error.
-        """
-        # File uploads use multipart form data, so we only send the auth header
-        # (no Content-Type — httpx sets it automatically for multipart).
-        cred = self._load()
-        headers = {"Authorization": f"Bearer {cred.bot_token}"}
-
-        form_data: Dict[str, Any] = {
-            "channels": ",".join(channels),
-        }
-
-        if filename:
-            form_data["filename"] = filename
-        if title:
-            form_data["title"] = title
-        if initial_comment:
-            form_data["initial_comment"] = initial_comment
-
-        files = None
-        if file_path:
-            files = {"file": open(file_path, "rb")}
-        elif content:
-            form_data["content"] = content
-
-        try:
-            r = httpx.post(f"{SLACK_API_BASE}/files.upload", headers=headers, data=form_data, files=files)
-        finally:
-            if files:
-                files["file"].close()
-
-        data = r.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("error", "Unknown error"), "details": data}
-
-        return data
diff --git a/app/external_comms/platforms/telegram_bot.py b/app/external_comms/platforms/telegram_bot.py
deleted file mode 100644
index bc895b4b..00000000
--- a/app/external_comms/platforms/telegram_bot.py
+++ /dev/null
@@ -1,616 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Telegram Bot API client — direct HTTP via httpx."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional, Union
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-TELEGRAM_API_BASE = "https://api.telegram.org"
-CREDENTIAL_FILE = "telegram_bot.json"
-
-POLL_TIMEOUT = 30       # seconds for long-polling
-RETRY_DELAY = 5         # seconds to wait after a poll error
-
-
-@dataclass
-class TelegramBotCredential:
-    bot_token: str = ""
-    bot_username: str = ""
-
-
-@register_client
-class TelegramBotClient(BasePlatformClient):
-    """Telegram Bot API platform client with long-polling support."""
-
-    PLATFORM_ID = "telegram_bot"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[TelegramBotCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._poll_offset: int = 0
-        self._bot_info: Optional[Dict[str, Any]] = None
-        self._catchup_done: bool = False
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        if has_credential(CREDENTIAL_FILE):
-            return True
-        # Auto-save shared bot credentials from env vars if available
-        try:
-            from app.config import TELEGRAM_SHARED_BOT_TOKEN, TELEGRAM_SHARED_BOT_USERNAME
-            if TELEGRAM_SHARED_BOT_TOKEN:
-                save_credential(CREDENTIAL_FILE, TelegramBotCredential(
-                    bot_token=TELEGRAM_SHARED_BOT_TOKEN,
-                    bot_username=TELEGRAM_SHARED_BOT_USERNAME or "",
-                ))
-                logger.info("[TELEGRAM_BOT] Auto-saved shared bot credentials from env vars")
-                return True
-        except Exception:
-            pass
-        return False
-
-    def _load(self) -> TelegramBotCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, TelegramBotCredential)
-        if self._cred is None:
-            raise RuntimeError("No Telegram Bot credentials. Use /telegram_bot login first.")
-        return self._cred
-
-    def _api_url(self, method: str) -> str:
-        cred = self._load()
-        return f"{TELEGRAM_API_BASE}/bot{cred.bot_token}/{method}"
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient overrides
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a text message to a chat.
-
-        Args:
-            recipient: Chat ID or username (@channel).
-            text: Message text (up to 4096 characters).
-            **kwargs: Optional ``parse_mode``, ``reply_to_message_id``,
-                      ``disable_notification``.
-
-        Returns:
-            API response with sent message or error.
-        """
-        parse_mode: Optional[str] = kwargs.get("parse_mode")
-        reply_to_message_id: Optional[int] = kwargs.get("reply_to_message_id")
-        disable_notification: bool = kwargs.get("disable_notification", False)
-
-        payload: Dict[str, Any] = {
-            "chat_id": recipient,
-            "text": text,
-        }
-
-        if parse_mode:
-            payload["parse_mode"] = parse_mode
-        if reply_to_message_id:
-            payload["reply_to_message_id"] = reply_to_message_id
-        if disable_notification:
-            payload["disable_notification"] = True
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("sendMessage"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    # ------------------------------------------------------------------
-    # Listening (long-polling)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        """Start long-polling for incoming messages.
-
-        Args:
-            callback: Async callback invoked with a ``PlatformMessage`` for
-                      every incoming text message.
-        """
-        if self._listening:
-            return
-
-        self._message_callback = callback
-
-        # Verify bot token before starting the loop
-        info = await self.get_me()
-        if "error" in info:
-            logger.error(f"[TELEGRAM_BOT] Invalid bot token: {info}")
-            raise RuntimeError(f"Invalid bot token: {info.get('error', 'unknown error')}")
-        self._bot_info = info.get("result", {})
-
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-        logger.info(
-            f"[TELEGRAM_BOT] Poller started for @{self._bot_info.get('username', 'unknown')}"
-        )
-
-    async def stop_listening(self) -> None:
-        """Stop the long-polling loop."""
-        if not self._listening:
-            return
-
-        self._listening = False
-
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-
-        self._poll_task = None
-        logger.info("[TELEGRAM_BOT] Poller stopped")
-
-    async def _poll_loop(self) -> None:
-        """Main long-polling loop with initial catchup."""
-        # Catchup: consume all pending updates without dispatching
-        logger.info("[TELEGRAM_BOT] Running initial catchup...")
-        try:
-            catchup_resp = await self._poll_updates()
-            catchup_updates = catchup_resp.get("result", [])
-            for update in catchup_updates:
-                # Just advance the offset without dispatching
-                update_id = update.get("update_id", 0)
-                self._poll_offset = update_id + 1
-            self._catchup_done = True
-            logger.info(f"[TELEGRAM_BOT] Catchup complete — {len(catchup_updates)} pending update(s) skipped")
-        except Exception as e:
-            logger.error(f"[TELEGRAM_BOT] Catchup error: {e}")
-            self._catchup_done = True  # proceed anyway
-
-        while self._listening:
-            try:
-                updates_resp = await self._poll_updates()
-                updates = updates_resp.get("result", [])
-                for update in updates:
-                    await self._process_update(update)
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[TELEGRAM_BOT] Poll error: {e}")
-                await asyncio.sleep(RETRY_DELAY)
-
-    async def _poll_updates(self) -> Dict[str, Any]:
-        """Fetch updates from Telegram using long-polling."""
-        try:
-            async with httpx.AsyncClient(
-                timeout=httpx.Timeout(POLL_TIMEOUT + 10)
-            ) as client:
-                resp = await client.get(
-                    self._api_url("getUpdates"),
-                    params={
-                        "offset": self._poll_offset,
-                        "timeout": POLL_TIMEOUT,
-                        "allowed_updates": ["message"],
-                    },
-                )
-                data = resp.json()
-
-                if data.get("ok"):
-                    return data
-                else:
-                    logger.warning(f"[TELEGRAM_BOT] getUpdates failed: {data}")
-                    return {"result": []}
-
-        except httpx.TimeoutException:
-            return {"result": []}
-        except Exception as e:
-            logger.error(f"[TELEGRAM_BOT] Error getting updates: {e}")
-            raise
-
-    async def _process_update(self, update: Dict[str, Any]) -> None:
-        """Process a single Telegram update and dispatch to callback."""
-        update_id = update.get("update_id", 0)
-        self._poll_offset = update_id + 1
-
-        message = update.get("message")
-        if not message:
-            return
-
-        text = message.get("text", "")
-        if not text:
-            return
-
-        from_user = message.get("from", {})
-        chat = message.get("chat", {})
-
-        # Build sender display name
-        sender_name = from_user.get("first_name", "")
-        if from_user.get("last_name"):
-            sender_name += f" {from_user['last_name']}"
-        if from_user.get("username"):
-            sender_name += f" (@{from_user['username']})"
-
-        ts = None
-        if message.get("date"):
-            try:
-                ts = datetime.fromtimestamp(message["date"], tz=timezone.utc)
-            except Exception:
-                pass
-
-        platform_msg = PlatformMessage(
-            platform="telegram_bot",
-            sender_id=str(from_user.get("id", "")),
-            sender_name=sender_name or str(from_user.get("id", "unknown")),
-            text=text,
-            channel_id=str(chat.get("id", "")),
-            channel_name=chat.get("title", chat.get("first_name", "")),
-            message_id=str(message.get("message_id", "")),
-            timestamp=ts,
-            raw=update,
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    # ------------------------------------------------------------------
-    # Bot API methods
-    # ------------------------------------------------------------------
-
-    async def get_me(self) -> Dict[str, Any]:
-        """Get basic information about the bot.
-
-        Returns:
-            API response with bot info or error.
-        """
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.get(self._api_url("getMe"))
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def send_photo(
-        self,
-        chat_id: Union[int, str],
-        photo: str,
-        caption: Optional[str] = None,
-        parse_mode: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Send a photo to a chat.
-
-        Args:
-            chat_id: Chat ID or username.
-            photo: File ID, URL, or file path.
-            caption: Photo caption.
-            parse_mode: Caption parse mode.
-
-        Returns:
-            API response with sent message or error.
-        """
-        payload: Dict[str, Any] = {
-            "chat_id": chat_id,
-            "photo": photo,
-        }
-
-        if caption:
-            payload["caption"] = caption
-        if parse_mode:
-            payload["parse_mode"] = parse_mode
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("sendPhoto"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def send_document(
-        self,
-        chat_id: Union[int, str],
-        document: str,
-        caption: Optional[str] = None,
-        parse_mode: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Send a document to a chat.
-
-        Args:
-            chat_id: Chat ID or username.
-            document: File ID, URL, or file path.
-            caption: Document caption.
-            parse_mode: Caption parse mode.
-
-        Returns:
-            API response with sent message or error.
-        """
-        payload: Dict[str, Any] = {
-            "chat_id": chat_id,
-            "document": document,
-        }
-
-        if caption:
-            payload["caption"] = caption
-        if parse_mode:
-            payload["parse_mode"] = parse_mode
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("sendDocument"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def get_updates(
-        self,
-        offset: Optional[int] = None,
-        limit: int = 100,
-        timeout: int = 0,
-        allowed_updates: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        """Get incoming updates using long polling.
-
-        Args:
-            offset: Identifier of the first update to return.
-            limit: Maximum number of updates (1-100).
-            timeout: Timeout in seconds for long polling.
-            allowed_updates: List of update types to receive.
-
-        Returns:
-            API response with updates or error.
-        """
-        payload: Dict[str, Any] = {
-            "limit": limit,
-            "timeout": timeout,
-        }
-
-        if offset is not None:
-            payload["offset"] = offset
-        if allowed_updates:
-            payload["allowed_updates"] = allowed_updates
-
-        async with httpx.AsyncClient(
-            timeout=httpx.Timeout(timeout + 10)
-        ) as client:
-            resp = await client.post(self._api_url("getUpdates"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def get_chat(
-        self,
-        chat_id: Union[int, str],
-    ) -> Dict[str, Any]:
-        """Get up-to-date information about a chat.
-
-        Args:
-            chat_id: Chat ID or username.
-
-        Returns:
-            API response with chat info or error.
-        """
-        payload = {"chat_id": chat_id}
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("getChat"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def get_chat_member(
-        self,
-        chat_id: Union[int, str],
-        user_id: int,
-    ) -> Dict[str, Any]:
-        """Get information about a member of a chat.
-
-        Args:
-            chat_id: Chat ID or username.
-            user_id: User ID.
-
-        Returns:
-            API response with chat member info or error.
-        """
-        payload = {
-            "chat_id": chat_id,
-            "user_id": user_id,
-        }
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("getChatMember"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def get_chat_members_count(
-        self,
-        chat_id: Union[int, str],
-    ) -> Dict[str, Any]:
-        """Get the number of members in a chat.
-
-        Args:
-            chat_id: Chat ID or username.
-
-        Returns:
-            API response with member count or error.
-        """
-        payload = {"chat_id": chat_id}
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("getChatMembersCount"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def forward_message(
-        self,
-        chat_id: Union[int, str],
-        from_chat_id: Union[int, str],
-        message_id: int,
-        disable_notification: bool = False,
-    ) -> Dict[str, Any]:
-        """Forward a message from one chat to another.
-
-        Args:
-            chat_id: Target chat ID.
-            from_chat_id: Source chat ID.
-            message_id: Message ID to forward.
-            disable_notification: Send silently.
-
-        Returns:
-            API response with forwarded message or error.
-        """
-        payload: Dict[str, Any] = {
-            "chat_id": chat_id,
-            "from_chat_id": from_chat_id,
-            "message_id": message_id,
-        }
-
-        if disable_notification:
-            payload["disable_notification"] = True
-
-        async with httpx.AsyncClient(timeout=10.0) as client:
-            resp = await client.post(self._api_url("forwardMessage"), json=payload)
-            data = resp.json()
-
-        if not data.get("ok"):
-            return {"error": data.get("description", "Unknown error"), "details": data}
-
-        return data
-
-    async def search_contact(self, name: str) -> Dict[str, Any]:
-        """Search for a contact by name from the bot's recent chat history.
-
-        Telegram bots can only interact with users who have started a
-        conversation with the bot. This searches through recent updates to
-        find matching users/chats by name.
-
-        Args:
-            name: Name to search for (case-insensitive, partial match).
-
-        Returns:
-            Dict with matching contacts or error.
-        """
-        updates_result = await self.get_updates(limit=100)
-
-        if "error" in updates_result:
-            return updates_result
-
-        updates = updates_result.get("result", [])
-
-        seen_ids: set = set()
-        contacts: List[Dict[str, Any]] = []
-        search_lower = name.lower()
-
-        for update in updates:
-            message = update.get("message") or update.get("edited_message")
-            if not message:
-                continue
-
-            # --- check the chat itself ---
-            chat = message.get("chat", {})
-            chat_id = chat.get("id")
-
-            if chat_id and chat_id not in seen_ids:
-                seen_ids.add(chat_id)
-
-                chat_type = chat.get("type", "")
-                if chat_type == "private":
-                    first_name = chat.get("first_name", "")
-                    last_name = chat.get("last_name", "")
-                    username = chat.get("username", "")
-                    full_name = f"{first_name} {last_name}".strip()
-                    searchable = f"{full_name} {username}".lower()
-                else:
-                    title = chat.get("title", "")
-                    username = chat.get("username", "")
-                    full_name = title
-                    searchable = f"{title} {username}".lower()
-
-                if search_lower in searchable:
-                    contacts.append({
-                        "chat_id": chat_id,
-                        "type": chat_type,
-                        "name": full_name or username,
-                        "username": username,
-                        "first_name": chat.get("first_name", ""),
-                        "last_name": chat.get("last_name", ""),
-                    })
-
-            # --- check the sender ---
-            sender = message.get("from", {})
-            sender_id = sender.get("id")
-
-            if sender_id and sender_id not in seen_ids:
-                seen_ids.add(sender_id)
-
-                first_name = sender.get("first_name", "")
-                last_name = sender.get("last_name", "")
-                username = sender.get("username", "")
-                full_name = f"{first_name} {last_name}".strip()
-                searchable = f"{full_name} {username}".lower()
-
-                if search_lower in searchable and not sender.get("is_bot"):
-                    contacts.append({
-                        "chat_id": sender_id,
-                        "type": "private",
-                        "name": full_name or username,
-                        "username": username,
-                        "first_name": first_name,
-                        "last_name": last_name,
-                    })
-
-        if contacts:
-            return {
-                "ok": True,
-                "result": {
-                    "contacts": contacts,
-                    "count": len(contacts),
-                },
-            }
-        else:
-            return {
-                "error": f"No contacts found matching '{name}'",
-                "details": {"searched_updates": len(updates), "name": name},
-            }
diff --git a/app/external_comms/platforms/telegram_mtproto_helpers.py b/app/external_comms/platforms/telegram_mtproto_helpers.py
deleted file mode 100644
index c9b1556f..00000000
--- a/app/external_comms/platforms/telegram_mtproto_helpers.py
+++ /dev/null
@@ -1,802 +0,0 @@
-"""
-Telegram MTProto (User Account) helper functions using Telethon.
-
-These functions provide full access to Telegram features including:
-- Reading message history from any chat
-- Listing all conversations (dialogs)
-- Sending messages as a user (not bot)
-- Accessing private chats and groups
-"""
-
-import asyncio
-from typing import Optional, Dict, Any, List, Union
-from telethon import TelegramClient
-from telethon.sessions import StringSession
-from telethon.errors import (
-    SessionPasswordNeededError,
-    PhoneCodeInvalidError,
-    PhoneCodeExpiredError,
-    PasswordHashInvalidError,
-    FloodWaitError,
-    AuthKeyUnregisteredError,
-)
-from telethon.tl.types import User, Chat, Channel, Message
-
-
-# Legacy: no longer used, kept for cleanup in complete_auth
-_pending_auth_sessions: Dict[str, TelegramClient] = {}
-
-
-async def start_auth(
-    api_id: int,
-    api_hash: str,
-    phone_number: str,
-) -> Dict[str, Any]:
-    """
-    Start the MTProto authentication flow by sending OTP to phone.
-
-    Args:
-        api_id: Telegram API ID from my.telegram.org
-        api_hash: Telegram API hash from my.telegram.org
-        phone_number: Phone number with country code (+1234567890)
-
-    Returns:
-        Dict with status, phone_code_hash, and session_string for completing auth
-    """
-    client = None
-    try:
-        # Create a new client with StringSession for portability
-        client = TelegramClient(StringSession(), api_id, api_hash)
-        await client.connect()
-
-        # Send code request
-        result = await client.send_code_request(phone_number)
-
-        # Save the session string - we need to reuse this session in complete_auth
-        # Telegram requires the same session for send_code_request and sign_in
-        session_string = client.session.save()
-
-        await client.disconnect()
-
-        return {
-            "ok": True,
-            "result": {
-                "phone_code_hash": result.phone_code_hash,
-                "phone_number": phone_number,
-                "session_string": session_string,  # Pass this to complete_auth
-                "status": "code_sent",
-            }
-        }
-
-    except FloodWaitError as e:
-        if client:
-            await client.disconnect()
-        return {
-            "error": f"Too many attempts. Please wait {e.seconds} seconds.",
-            "details": {"flood_wait_seconds": e.seconds}
-        }
-    except Exception as e:
-        if client:
-            try:
-                await client.disconnect()
-            except Exception:
-                pass
-        return {
-            "error": f"Failed to start auth: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def qr_login(
-    api_id: int,
-    api_hash: str,
-    on_qr_url: Optional[Any] = None,
-    timeout: int = 120,
-) -> Dict[str, Any]:
-    """
-    Login to Telegram by scanning a QR code with the phone app.
-
-    Uses Telethon's built-in ``client.qr_login()`` which handles the full
-    ExportLoginToken → AcceptLoginToken → ImportLoginToken flow.
-
-    Args:
-        api_id: Telegram API ID from my.telegram.org
-        api_hash: Telegram API hash from my.telegram.org
-        on_qr_url: Optional callback(url: str) called with the ``tg://login?token=...``
-                    URL so the caller can render it as a QR code.
-        timeout: Seconds to wait for the user to scan (default 120).
-
-    Returns:
-        Dict with session_string and user info on success, or error details.
-    """
-    client = None
-    try:
-        client = TelegramClient(StringSession(), api_id, api_hash)
-        await client.connect()
-
-        qr = await client.qr_login()
-
-        # Notify caller so it can display the QR code
-        if on_qr_url:
-            on_qr_url(qr.url)
-
-        # Wait for the user to scan the QR code
-        # If the token expires (every ~30s) Telethon auto-refreshes,
-        # but we need to re-notify the caller with the new URL.
-        try:
-            user = await asyncio.wait_for(qr.wait(timeout), timeout=timeout)
-        except asyncio.TimeoutError:
-            await client.disconnect()
-            return {
-                "error": "QR login timed out. Please try again.",
-                "details": {"status": "timeout"},
-            }
-
-    except SessionPasswordNeededError:
-        # 2FA is enabled — need password to finish.
-        # Save session so handler can call sign_in(password=...) later.
-        session_string = client.session.save()
-        await client.disconnect()
-        return {
-            "error": "Two-factor authentication is enabled. Please provide your 2FA password.",
-            "details": {
-                "status": "2fa_required",
-                "session_string": session_string,
-            },
-        }
-    except Exception as e:
-        if client:
-            try:
-                await client.disconnect()
-            except Exception:
-                pass
-        return {
-            "error": f"QR login failed: {str(e)}",
-            "details": {"exception": type(e).__name__},
-        }
-
-    # Success — extract user info and session string
-    try:
-        me = await client.get_me()
-        session_string = client.session.save()
-        await client.disconnect()
-
-        return {
-            "ok": True,
-            "result": {
-                "session_string": session_string,
-                "user_id": me.id,
-                "first_name": me.first_name or "",
-                "last_name": me.last_name or "",
-                "username": me.username or "",
-                "phone": me.phone or "",
-                "status": "authenticated",
-            },
-        }
-    except Exception as e:
-        if client:
-            try:
-                await client.disconnect()
-            except Exception:
-                pass
-        return {
-            "error": f"QR login succeeded but failed to get user info: {str(e)}",
-            "details": {"exception": type(e).__name__},
-        }
-
-
-async def complete_auth(
-    api_id: int,
-    api_hash: str,
-    phone_number: str,
-    code: str,
-    phone_code_hash: str,
-    password: Optional[str] = None,
-    pending_session_string: Optional[str] = None,
-) -> Dict[str, Any]:
-    """
-    Complete MTProto authentication with OTP code (and optional 2FA password).
-
-    Args:
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        phone_number: Phone number used in start_auth
-        code: OTP code received via SMS/Telegram
-        phone_code_hash: Hash returned from start_auth
-        password: Optional 2FA password if enabled
-        pending_session_string: Session string from start_auth (required)
-
-    Returns:
-        Dict with session_string and user info on success
-    """
-    client = None
-    try:
-        # Use the session from start_auth - Telegram requires the same session
-        # for send_code_request and sign_in
-        session = StringSession(pending_session_string) if pending_session_string else StringSession()
-        client = TelegramClient(session, api_id, api_hash)
-        await client.connect()
-
-        try:
-            # Try to sign in with code
-            await client.sign_in(
-                phone=phone_number,
-                code=code,
-                phone_code_hash=phone_code_hash,
-            )
-
-        except SessionPasswordNeededError:
-            # 2FA is enabled
-            if not password:
-                await client.disconnect()
-                return {
-                    "error": "Two-factor authentication is enabled. Please provide password.",
-                    "details": {"requires_2fa": True, "status": "2fa_required"}
-                }
-
-            try:
-                await client.sign_in(password=password)
-            except PasswordHashInvalidError:
-                await client.disconnect()
-                return {
-                    "error": "Invalid 2FA password.",
-                    "details": {"status": "invalid_password"}
-                }
-
-        # Get user info
-        me = await client.get_me()
-        session_string = client.session.save()
-
-        # Clean up pending session (from start_auth, if any)
-        if phone_number in _pending_auth_sessions:
-            try:
-                old_client = _pending_auth_sessions.pop(phone_number)
-                await old_client.disconnect()
-            except Exception:
-                pass
-
-        await client.disconnect()
-
-        return {
-            "ok": True,
-            "result": {
-                "session_string": session_string,
-                "user_id": me.id,
-                "first_name": me.first_name or "",
-                "last_name": me.last_name or "",
-                "username": me.username or "",
-                "phone": me.phone or phone_number,
-                "status": "authenticated",
-            }
-        }
-
-    except PhoneCodeInvalidError:
-        if client:
-            await client.disconnect()
-        return {
-            "error": "Invalid verification code.",
-            "details": {"status": "invalid_code"}
-        }
-    except PhoneCodeExpiredError:
-        if client:
-            await client.disconnect()
-        return {
-            "error": "Verification code has expired. Please request a new one.",
-            "details": {"status": "code_expired"}
-        }
-    except FloodWaitError as e:
-        if client:
-            await client.disconnect()
-        return {
-            "error": f"Too many attempts. Please wait {e.seconds} seconds.",
-            "details": {"flood_wait_seconds": e.seconds}
-        }
-    except Exception as e:
-        if client:
-            try:
-                await client.disconnect()
-            except Exception:
-                pass
-        return {
-            "error": f"Failed to complete auth: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def get_me(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-) -> Dict[str, Any]:
-    """
-    Get information about the authenticated user.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-
-    Returns:
-        Dict with user info
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            me = await client.get_me()
-
-            return {
-                "ok": True,
-                "result": {
-                    "user_id": me.id,
-                    "first_name": me.first_name or "",
-                    "last_name": me.last_name or "",
-                    "username": me.username or "",
-                    "phone": me.phone or "",
-                    "is_bot": me.bot,
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to get user info: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def get_dialogs(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-    limit: int = 50,
-) -> Dict[str, Any]:
-    """
-    Get list of all conversations (dialogs/chats).
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        limit: Maximum number of dialogs to return
-
-    Returns:
-        Dict with list of dialogs
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            dialogs = await client.get_dialogs(limit=limit)
-
-            result = []
-            for dialog in dialogs:
-                entity = dialog.entity
-
-                dialog_info = {
-                    "id": dialog.id,
-                    "name": dialog.name or "",
-                    "unread_count": dialog.unread_count,
-                    "is_pinned": dialog.pinned,
-                    "is_archived": dialog.archived,
-                }
-
-                # Determine type and add type-specific info
-                if isinstance(entity, User):
-                    dialog_info["type"] = "private"
-                    dialog_info["username"] = entity.username or ""
-                    dialog_info["phone"] = entity.phone or ""
-                    dialog_info["is_bot"] = entity.bot
-                elif isinstance(entity, Chat):
-                    dialog_info["type"] = "group"
-                    dialog_info["participants_count"] = getattr(entity, 'participants_count', None)
-                elif isinstance(entity, Channel):
-                    dialog_info["type"] = "channel" if entity.broadcast else "supergroup"
-                    dialog_info["username"] = entity.username or ""
-                    dialog_info["participants_count"] = getattr(entity, 'participants_count', None)
-                else:
-                    dialog_info["type"] = "unknown"
-
-                # Last message preview
-                if dialog.message:
-                    dialog_info["last_message"] = {
-                        "id": dialog.message.id,
-                        "date": dialog.message.date.isoformat() if dialog.message.date else None,
-                        "text": dialog.message.text[:100] if dialog.message.text else "",
-                    }
-
-                result.append(dialog_info)
-
-            return {
-                "ok": True,
-                "result": {
-                    "dialogs": result,
-                    "count": len(result),
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to get dialogs: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def get_messages(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-    chat_id: Union[int, str],
-    limit: int = 50,
-    offset_id: int = 0,
-) -> Dict[str, Any]:
-    """
-    Get message history from a chat.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        chat_id: Chat ID, username, or phone number
-        limit: Maximum number of messages to return
-        offset_id: Message ID to start from (for pagination)
-
-    Returns:
-        Dict with list of messages
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            # Get entity (handles various formats)
-            entity = await client.get_entity(chat_id)
-
-            # Get messages
-            messages = await client.get_messages(
-                entity,
-                limit=limit,
-                offset_id=offset_id,
-            )
-
-            result = []
-            for msg in messages:
-                message_info = {
-                    "id": msg.id,
-                    "date": msg.date.isoformat() if msg.date else None,
-                    "text": msg.text or "",
-                    "out": msg.out,  # True if sent by us
-                }
-
-                # Sender info
-                if msg.sender:
-                    sender = msg.sender
-                    message_info["sender"] = {
-                        "id": sender.id,
-                        "name": _get_display_name(sender),
-                        "username": getattr(sender, 'username', None) or "",
-                    }
-
-                # Media info
-                if msg.media:
-                    message_info["has_media"] = True
-                    message_info["media_type"] = type(msg.media).__name__
-
-                # Reply info
-                if msg.reply_to:
-                    message_info["reply_to_msg_id"] = msg.reply_to.reply_to_msg_id
-
-                # Forward info
-                if msg.forward:
-                    message_info["is_forwarded"] = True
-
-                result.append(message_info)
-
-            # Get chat info
-            chat_info = {
-                "id": entity.id,
-                "name": _get_display_name(entity),
-                "type": _get_entity_type(entity),
-            }
-
-            return {
-                "ok": True,
-                "result": {
-                    "chat": chat_info,
-                    "messages": result,
-                    "count": len(result),
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except ValueError as e:
-        return {
-            "error": f"Could not find chat: {str(e)}",
-            "details": {"chat_id": str(chat_id)}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to get messages: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def send_message(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-    chat_id: Union[int, str],
-    text: str,
-    reply_to: Optional[int] = None,
-) -> Dict[str, Any]:
-    """
-    Send a text message to a chat.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        chat_id: Chat ID, username, or phone number
-        text: Message text
-        reply_to: Optional message ID to reply to
-
-    Returns:
-        Dict with sent message info
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            entity = await client.get_entity(chat_id)
-
-            msg = await client.send_message(
-                entity,
-                text,
-                reply_to=reply_to,
-            )
-
-            return {
-                "ok": True,
-                "result": {
-                    "message_id": msg.id,
-                    "date": msg.date.isoformat() if msg.date else None,
-                    "chat_id": entity.id,
-                    "text": msg.text,
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except ValueError as e:
-        return {
-            "error": f"Could not find chat: {str(e)}",
-            "details": {"chat_id": str(chat_id)}
-        }
-    except FloodWaitError as e:
-        return {
-            "error": f"Rate limited. Please wait {e.seconds} seconds.",
-            "details": {"flood_wait_seconds": e.seconds}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to send message: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def send_file(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-    chat_id: Union[int, str],
-    file_path: str,
-    caption: Optional[str] = None,
-    reply_to: Optional[int] = None,
-) -> Dict[str, Any]:
-    """
-    Send a file/media to a chat.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        chat_id: Chat ID, username, or phone number
-        file_path: Path to file or URL
-        caption: Optional caption for the file
-        reply_to: Optional message ID to reply to
-
-    Returns:
-        Dict with sent message info
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            entity = await client.get_entity(chat_id)
-
-            msg = await client.send_file(
-                entity,
-                file_path,
-                caption=caption,
-                reply_to=reply_to,
-            )
-
-            return {
-                "ok": True,
-                "result": {
-                    "message_id": msg.id,
-                    "date": msg.date.isoformat() if msg.date else None,
-                    "chat_id": entity.id,
-                    "has_media": True,
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except ValueError as e:
-        return {
-            "error": f"Could not find chat: {str(e)}",
-            "details": {"chat_id": str(chat_id)}
-        }
-    except FileNotFoundError:
-        return {
-            "error": f"File not found: {file_path}",
-            "details": {"file_path": file_path}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to send file: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def search_contacts(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-    query: str,
-    limit: int = 20,
-) -> Dict[str, Any]:
-    """
-    Search for contacts/users by name or username.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-        query: Search query (name or username)
-        limit: Maximum results to return
-
-    Returns:
-        Dict with matching contacts
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            # Search global
-            result = await client.get_dialogs(limit=100)
-
-            contacts = []
-            query_lower = query.lower()
-
-            for dialog in result:
-                entity = dialog.entity
-                name = _get_display_name(entity).lower()
-                username = (getattr(entity, 'username', '') or '').lower()
-
-                if query_lower in name or query_lower in username:
-                    contact_info = {
-                        "id": entity.id,
-                        "name": _get_display_name(entity),
-                        "username": getattr(entity, 'username', None) or "",
-                        "type": _get_entity_type(entity),
-                    }
-
-                    if isinstance(entity, User):
-                        contact_info["phone"] = entity.phone or ""
-                        contact_info["is_bot"] = entity.bot
-
-                    contacts.append(contact_info)
-
-                    if len(contacts) >= limit:
-                        break
-
-            return {
-                "ok": True,
-                "result": {
-                    "contacts": contacts,
-                    "count": len(contacts),
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "error": "Session has expired or been revoked. Please re-authenticate.",
-            "details": {"status": "session_expired"}
-        }
-    except Exception as e:
-        return {
-            "error": f"Failed to search contacts: {str(e)}",
-            "details": {"exception": type(e).__name__}
-        }
-
-
-async def validate_session(
-    session_string: str,
-    api_id: int,
-    api_hash: str,
-) -> Dict[str, Any]:
-    """
-    Validate if a session is still active.
-
-    Args:
-        session_string: Telethon StringSession
-        api_id: Telegram API ID
-        api_hash: Telegram API hash
-
-    Returns:
-        Dict with validation status
-    """
-    try:
-        async with TelegramClient(StringSession(session_string), api_id, api_hash) as client:
-            me = await client.get_me()
-
-            return {
-                "ok": True,
-                "result": {
-                    "valid": True,
-                    "user_id": me.id,
-                    "username": me.username or "",
-                }
-            }
-
-    except AuthKeyUnregisteredError:
-        return {
-            "ok": True,
-            "result": {
-                "valid": False,
-                "reason": "session_expired",
-            }
-        }
-    except Exception as e:
-        return {
-            "ok": True,
-            "result": {
-                "valid": False,
-                "reason": str(e),
-            }
-        }
-
-
-def _get_display_name(entity) -> str:
-    """Get display name for any entity type."""
-    if isinstance(entity, User):
-        parts = []
-        if entity.first_name:
-            parts.append(entity.first_name)
-        if entity.last_name:
-            parts.append(entity.last_name)
-        return " ".join(parts) or entity.username or str(entity.id)
-    elif hasattr(entity, 'title'):
-        return entity.title or ""
-    else:
-        return str(entity.id)
-
-
-def _get_entity_type(entity) -> str:
-    """Get type string for any entity."""
-    if isinstance(entity, User):
-        return "bot" if entity.bot else "user"
-    elif isinstance(entity, Chat):
-        return "group"
-    elif isinstance(entity, Channel):
-        return "channel" if entity.broadcast else "supergroup"
-    else:
-        return "unknown"
diff --git a/app/external_comms/platforms/telegram_user.py b/app/external_comms/platforms/telegram_user.py
deleted file mode 100644
index d80e068b..00000000
--- a/app/external_comms/platforms/telegram_user.py
+++ /dev/null
@@ -1,716 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Telegram MTProto (user account) client — uses Telethon with StringSession."""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from dataclasses import dataclass
-from datetime import timezone
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Union
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-CREDENTIAL_FILE = "telegram_user.json"
-
-
-@dataclass
-class TelegramUserCredential:
-    session_string: str = ""
-    api_id: str = ""        # stored as str; cast to int when used
-    api_hash: str = ""
-    phone_number: str = ""
-
-
-@register_client
-class TelegramUserClient(BasePlatformClient):
-    """Telegram MTProto client for user-account operations via Telethon."""
-
-    PLATFORM_ID = "telegram_user"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[TelegramUserCredential] = None
-        self._live_client = None          # persistent TelegramClient for listening
-        self._live_loop = None            # event loop the live client was created on
-        self._send_queue: Optional[asyncio.Queue] = None  # queue for sending via live client
-        self._send_task = None
-        self._my_user_id: Optional[int] = None
-        self._agent_sent_ids: set = set()  # track IDs of messages sent by the agent
-
-    # Generic terms the LLM may use to mean "send to self / Saved Messages"
-    _OWNER_ALIASES = {"user", "owner", "me", "self"}
-
-    def _resolve_recipient(self, recipient: str) -> str:
-        """If *recipient* is a generic alias like 'user', resolve to Saved Messages."""
-        if recipient.strip().lower() in self._OWNER_ALIASES:
-            # "me" is Telethon's built-in shortcut for Saved Messages
-            if self._my_user_id:
-                logger.info(f"[TELEGRAM_USER] Resolved '{recipient}' to own user ID {self._my_user_id}")
-                return str(self._my_user_id)
-            logger.info(f"[TELEGRAM_USER] Resolved '{recipient}' to 'me' (Saved Messages)")
-            return "me"
-        return recipient
-
-    @property
-    def _agent_prefix(self) -> str:
-        """Return prefix like '[AgentName] ' using the configured agent name."""
-        try:
-            from app.onboarding import onboarding_manager
-            name = onboarding_manager.state.agent_name or "AGENT"
-        except Exception:
-            name = "AGENT"
-        return f"[{name}] "
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> TelegramUserCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, TelegramUserCredential)
-        if self._cred is None:
-            raise RuntimeError("No Telegram User credentials. Use /telegram_user login first.")
-        return self._cred
-
-    def _session_params(self):
-        """Return (session, api_id, api_hash) for creating a TelegramClient."""
-        from telethon.sessions import StringSession
-
-        cred = self._load()
-        return StringSession(cred.session_string), int(cred.api_id), cred.api_hash
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient overrides
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    # ------------------------------------------------------------------
-    # Listening (Telethon event handler)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        """Start listening for incoming messages via MTProto.
-
-        Captures:
-        - Saved Messages (self-messages) → is_self_message = True
-        - Incoming messages from others → is_self_message = False
-        - Outgoing messages to others are ignored.
-        """
-        if self._listening:
-            return
-
-        self._message_callback = callback
-
-        try:
-            from telethon import TelegramClient, events
-        except ImportError:
-            raise RuntimeError("telethon is not installed")
-
-        session, api_id, api_hash = self._session_params()
-        client = TelegramClient(session, api_id, api_hash)
-        await client.connect()
-        self._live_loop = asyncio.get_event_loop()
-
-        if not await client.is_user_authorized():
-            await client.disconnect()
-            raise RuntimeError("Telegram user session expired or revoked. Please re-authenticate.")
-
-        me = await client.get_me()
-        self._my_user_id = me.id
-        self._live_client = client
-
-        @client.on(events.NewMessage)
-        async def _on_new_message(event):
-            try:
-                await self._handle_event(event)
-            except Exception as e:
-                logger.error(f"[TELEGRAM_USER] Error handling message event: {e}")
-
-        # Catch up on missed updates
-        await client.catch_up()
-
-        # Send queue processor — runs on the live client's loop
-        self._send_queue = asyncio.Queue()
-
-        async def _send_processor():
-            while self._listening:
-                try:
-                    item = await asyncio.wait_for(self._send_queue.get(), timeout=60)
-                    recipient, text, reply_to, result_future = item
-                    try:
-                        try:
-                            entity = await client.get_entity(int(recipient) if recipient.lstrip('-').isdigit() else recipient)
-                        except ValueError:
-                            entity = await client.get_entity(recipient)
-                        msg = await client.send_message(entity, text, reply_to=reply_to)
-                        result_future.set_result(msg)
-                    except Exception as e:
-                        result_future.set_exception(e)
-                except asyncio.TimeoutError:
-                    # No messages to send — do a keepalive catch_up
-                    try:
-                        if self._live_client and self._live_client.is_connected():
-                            await self._live_client.catch_up()
-                    except Exception:
-                        pass
-                except asyncio.CancelledError:
-                    break
-                except Exception:
-                    pass
-        self._send_task = asyncio.create_task(_send_processor())
-
-        self._listening = True
-        logger.info(
-            f"[TELEGRAM_USER] Listener started for user {me.first_name or ''} "
-            f"(@{me.username or 'N/A'}, id={me.id})"
-        )
-
-    async def stop_listening(self) -> None:
-        """Stop listening and disconnect the persistent client."""
-        if not self._listening:
-            return
-
-        self._listening = False
-
-        for task in [getattr(self, '_run_task', None), getattr(self, '_send_task', None)]:
-            if task and not task.done():
-                task.cancel()
-        self._run_task = None
-        self._send_task = None
-        self._send_queue = None
-
-        if self._live_client:
-            try:
-                await self._live_client.disconnect()
-            except Exception:
-                pass
-            self._live_client = None
-
-        logger.info("[TELEGRAM_USER] Listener stopped")
-
-    async def _handle_event(self, event) -> None:
-        """Process a Telethon NewMessage event."""
-        msg = event.message
-        if not msg or not msg.text:
-            return
-
-        chat_id = event.chat_id
-        is_saved_messages = (chat_id == self._my_user_id)
-
-        # Outgoing message to someone else → ignore
-        if msg.out and not is_saved_messages:
-            return
-
-        # Skip agent-sent self-messages (prevents echo loop)
-        if is_saved_messages and msg.out:
-            msg_id_str = str(msg.id)
-            if msg_id_str in self._agent_sent_ids:
-                self._agent_sent_ids.discard(msg_id_str)
-                logger.debug(f"[TELEGRAM_USER] Skipping agent-sent message (ID match): {msg_id_str}")
-                return
-            if msg.text.startswith(self._agent_prefix):
-                logger.debug(f"[TELEGRAM_USER] Skipping agent-sent message (prefix match): {msg.text[:50]}...")
-                return
-
-        sender = await event.get_sender()
-        chat = await event.get_chat()
-
-        sender_name = _get_display_name(sender) if sender else "Unknown"
-        channel_name = _get_display_name(chat) if chat else ""
-
-        platform_msg = PlatformMessage(
-            platform="telegram_user",
-            sender_id=str(sender.id if sender else self._my_user_id),
-            sender_name=sender_name,
-            text=msg.text,
-            channel_id=str(chat_id),
-            channel_name=channel_name if not is_saved_messages else "Saved Messages",
-            message_id=str(msg.id),
-            timestamp=msg.date.astimezone(timezone.utc) if msg.date else None,
-            raw={"is_self_message": is_saved_messages},
-        )
-
-        if self._message_callback:
-            await self._message_callback(platform_msg)
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a text message to a chat as the user account. Prepends agent prefix.
-
-        Args:
-            recipient: Chat ID, username, or phone number.
-            text: Message text.
-            **kwargs: Optional ``reply_to`` (int) message ID.
-
-        Returns:
-            Dict with sent message info or error.
-        """
-        reply_to: Optional[int] = kwargs.get("reply_to")
-        resolved = self._resolve_recipient(recipient)
-        prefixed_text = f"{self._agent_prefix}{text}"
-
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError, FloodWaitError
-
-            # Queue the send to the live client's send processor (avoids event loop issues)
-            if self._send_queue is not None and self._live_client and self._live_client.is_connected():
-                loop = asyncio.get_event_loop()
-                result_future = loop.create_future()
-                await self._send_queue.put((resolved, prefixed_text, reply_to, result_future))
-                msg = await asyncio.wait_for(result_future, timeout=30)
-            else:
-                # Fallback: new client (listener not running)
-                session, api_id, api_hash = self._session_params()
-                async with TelegramClient(session, api_id, api_hash) as client:
-                    try:
-                        entity = await client.get_entity(int(resolved) if resolved.lstrip('-').isdigit() else resolved)
-                    except ValueError:
-                        entity = await client.get_entity(resolved)
-                    msg = await client.send_message(entity, prefixed_text, reply_to=reply_to)
-
-                # Track sent message ID to filter echo in _handle_event
-                self._agent_sent_ids.add(str(msg.id))
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "message_id": msg.id,
-                        "date": msg.date.isoformat() if msg.date else None,
-                        "chat_id": getattr(msg, 'chat_id', None) or resolved,
-                        "text": msg.text,
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except ValueError as e:
-            return {
-                "error": f"Could not find chat: {e}",
-                "details": {"chat_id": str(recipient)},
-            }
-        except FloodWaitError as e:
-            return {
-                "error": f"Rate limited. Please wait {e.seconds} seconds.",
-                "details": {"flood_wait_seconds": e.seconds},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to send message: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-    # ------------------------------------------------------------------
-    # MTProto API methods
-    # ------------------------------------------------------------------
-
-    async def get_me(self) -> Dict[str, Any]:
-        """Get information about the authenticated user.
-
-        Returns:
-            Dict with user info or error.
-        """
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError
-
-            session, api_id, api_hash = self._session_params()
-
-            async with TelegramClient(session, api_id, api_hash) as client:
-                me = await client.get_me()
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "user_id": me.id,
-                        "first_name": me.first_name or "",
-                        "last_name": me.last_name or "",
-                        "username": me.username or "",
-                        "phone": me.phone or "",
-                        "is_bot": me.bot,
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to get user info: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-    async def get_dialogs(self, limit: int = 50) -> Dict[str, Any]:
-        """Get list of all conversations (dialogs/chats).
-
-        Args:
-            limit: Maximum number of dialogs to return.
-
-        Returns:
-            Dict with list of dialogs or error.
-        """
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError
-            from telethon.tl.types import User, Chat, Channel
-
-            session, api_id, api_hash = self._session_params()
-
-            async with TelegramClient(session, api_id, api_hash) as client:
-                dialogs = await client.get_dialogs(limit=limit)
-
-                result = []
-                for dialog in dialogs:
-                    entity = dialog.entity
-
-                    dialog_info: Dict[str, Any] = {
-                        "id": dialog.id,
-                        "name": dialog.name or "",
-                        "unread_count": dialog.unread_count,
-                        "is_pinned": dialog.pinned,
-                        "is_archived": dialog.archived,
-                    }
-
-                    if isinstance(entity, User):
-                        dialog_info["type"] = "private"
-                        dialog_info["username"] = entity.username or ""
-                        dialog_info["phone"] = entity.phone or ""
-                        dialog_info["is_bot"] = entity.bot
-                    elif isinstance(entity, Chat):
-                        dialog_info["type"] = "group"
-                        dialog_info["participants_count"] = getattr(entity, "participants_count", None)
-                    elif isinstance(entity, Channel):
-                        dialog_info["type"] = "channel" if entity.broadcast else "supergroup"
-                        dialog_info["username"] = entity.username or ""
-                        dialog_info["participants_count"] = getattr(entity, "participants_count", None)
-                    else:
-                        dialog_info["type"] = "unknown"
-
-                    if dialog.message:
-                        dialog_info["last_message"] = {
-                            "id": dialog.message.id,
-                            "date": dialog.message.date.isoformat() if dialog.message.date else None,
-                            "text": dialog.message.text[:100] if dialog.message.text else "",
-                        }
-
-                    result.append(dialog_info)
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "dialogs": result,
-                        "count": len(result),
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to get dialogs: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-    async def get_messages(
-        self,
-        chat_id: Union[int, str],
-        limit: int = 50,
-        offset_id: int = 0,
-    ) -> Dict[str, Any]:
-        """Get message history from a chat.
-
-        Args:
-            chat_id: Chat ID, username, or phone number.
-            limit: Maximum number of messages to return.
-            offset_id: Message ID to start from (for pagination).
-
-        Returns:
-            Dict with list of messages or error.
-        """
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError
-            from telethon.tl.types import User, Chat, Channel
-
-            session, api_id, api_hash = self._session_params()
-
-            async with TelegramClient(session, api_id, api_hash) as client:
-                entity = await client.get_entity(chat_id)
-                messages = await client.get_messages(entity, limit=limit, offset_id=offset_id)
-
-                result = []
-                for msg in messages:
-                    message_info: Dict[str, Any] = {
-                        "id": msg.id,
-                        "date": msg.date.isoformat() if msg.date else None,
-                        "text": msg.text or "",
-                        "out": msg.out,
-                    }
-
-                    if msg.sender:
-                        sender = msg.sender
-                        message_info["sender"] = {
-                            "id": sender.id,
-                            "name": _get_display_name(sender),
-                            "username": getattr(sender, "username", None) or "",
-                        }
-
-                    if msg.media:
-                        message_info["has_media"] = True
-                        message_info["media_type"] = type(msg.media).__name__
-
-                    if msg.reply_to:
-                        message_info["reply_to_msg_id"] = msg.reply_to.reply_to_msg_id
-
-                    if msg.forward:
-                        message_info["is_forwarded"] = True
-
-                    result.append(message_info)
-
-                chat_info = {
-                    "id": entity.id,
-                    "name": _get_display_name(entity),
-                    "type": _get_entity_type(entity),
-                }
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "chat": chat_info,
-                        "messages": result,
-                        "count": len(result),
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except ValueError as e:
-            return {
-                "error": f"Could not find chat: {e}",
-                "details": {"chat_id": str(chat_id)},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to get messages: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-    async def send_file(
-        self,
-        chat_id: Union[int, str],
-        file_path: str,
-        caption: Optional[str] = None,
-        reply_to: Optional[int] = None,
-    ) -> Dict[str, Any]:
-        """Send a file/media to a chat.
-
-        Args:
-            chat_id: Chat ID, username, or phone number.
-            file_path: Path to file or URL.
-            caption: Optional caption for the file.
-            reply_to: Optional message ID to reply to.
-
-        Returns:
-            Dict with sent message info or error.
-        """
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError, FloodWaitError
-
-            session, api_id, api_hash = self._session_params()
-
-            async with TelegramClient(session, api_id, api_hash) as client:
-                entity = await client.get_entity(chat_id)
-                msg = await client.send_file(
-                    entity,
-                    file_path,
-                    caption=caption,
-                    reply_to=reply_to,
-                )
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "message_id": msg.id,
-                        "date": msg.date.isoformat() if msg.date else None,
-                        "chat_id": entity.id,
-                        "has_media": True,
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except ValueError as e:
-            return {
-                "error": f"Could not find chat: {e}",
-                "details": {"chat_id": str(chat_id)},
-            }
-        except FileNotFoundError:
-            return {
-                "error": f"File not found: {file_path}",
-                "details": {"file_path": file_path},
-            }
-        except FloodWaitError as e:
-            return {
-                "error": f"Rate limited. Please wait {e.seconds} seconds.",
-                "details": {"flood_wait_seconds": e.seconds},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to send file: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-    async def search_contacts(
-        self,
-        query: str,
-        limit: int = 20,
-    ) -> Dict[str, Any]:
-        """Search for contacts/users by name or username.
-
-        Args:
-            query: Search query (name or username).
-            limit: Maximum results to return.
-
-        Returns:
-            Dict with matching contacts or error.
-        """
-        try:
-            from telethon import TelegramClient
-            from telethon.errors import AuthKeyUnregisteredError
-            from telethon.tl.types import User
-
-            session, api_id, api_hash = self._session_params()
-
-            async with TelegramClient(session, api_id, api_hash) as client:
-                dialogs = await client.get_dialogs(limit=100)
-
-                contacts: List[Dict[str, Any]] = []
-                query_lower = query.lower()
-
-                for dialog in dialogs:
-                    entity = dialog.entity
-                    name = _get_display_name(entity).lower()
-                    username = (getattr(entity, "username", "") or "").lower()
-
-                    if query_lower in name or query_lower in username:
-                        contact_info: Dict[str, Any] = {
-                            "id": entity.id,
-                            "name": _get_display_name(entity),
-                            "username": getattr(entity, "username", None) or "",
-                            "type": _get_entity_type(entity),
-                        }
-
-                        if isinstance(entity, User):
-                            contact_info["phone"] = entity.phone or ""
-                            contact_info["is_bot"] = entity.bot
-
-                        contacts.append(contact_info)
-
-                        if len(contacts) >= limit:
-                            break
-
-                return {
-                    "ok": True,
-                    "result": {
-                        "contacts": contacts,
-                        "count": len(contacts),
-                    },
-                }
-
-        except ImportError:
-            return {"error": "telethon is not installed", "details": {}}
-        except AuthKeyUnregisteredError:
-            return {
-                "error": "Session has expired or been revoked. Please re-authenticate.",
-                "details": {"status": "session_expired"},
-            }
-        except Exception as e:
-            return {
-                "error": f"Failed to search contacts: {e}",
-                "details": {"exception": type(e).__name__},
-            }
-
-
-# ------------------------------------------------------------------
-# Private helpers (mirror of mtproto_helpers utilities)
-# ------------------------------------------------------------------
-
-def _get_display_name(entity) -> str:
-    """Get display name for any Telethon entity type."""
-    try:
-        from telethon.tl.types import User
-    except ImportError:
-        return str(getattr(entity, "id", ""))
-
-    if isinstance(entity, User):
-        parts = []
-        if entity.first_name:
-            parts.append(entity.first_name)
-        if entity.last_name:
-            parts.append(entity.last_name)
-        return " ".join(parts) or entity.username or str(entity.id)
-    elif hasattr(entity, "title"):
-        return entity.title or ""
-    else:
-        return str(entity.id)
-
-
-def _get_entity_type(entity) -> str:
-    """Get type string for any Telethon entity."""
-    try:
-        from telethon.tl.types import User, Chat, Channel
-    except ImportError:
-        return "unknown"
-
-    if isinstance(entity, User):
-        return "bot" if entity.bot else "user"
-    elif isinstance(entity, Chat):
-        return "group"
-    elif isinstance(entity, Channel):
-        return "channel" if entity.broadcast else "supergroup"
-    else:
-        return "unknown"
diff --git a/app/external_comms/platforms/twitter.py b/app/external_comms/platforms/twitter.py
deleted file mode 100644
index 9fc76143..00000000
--- a/app/external_comms/platforms/twitter.py
+++ /dev/null
@@ -1,493 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Twitter/X REST API v2 client — direct HTTP via httpx with OAuth 1.0a.
-
-Supports posting tweets, reading timelines, searching, managing likes/retweets,
-and polling for mentions. An optional **watch_tag** lets users restrict
-mention triggers to those containing a specific keyword.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import hashlib
-import hmac
-import logging
-import time
-import urllib.parse
-import secrets
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-TWITTER_API = "https://api.twitter.com/2"
-CREDENTIAL_FILE = "twitter.json"
-
-POLL_INTERVAL = 30      # seconds between mention polls
-RETRY_DELAY = 60        # seconds to wait after a poll error
-
-
-@dataclass
-class TwitterCredential:
-    api_key: str = ""
-    api_secret: str = ""
-    access_token: str = ""
-    access_token_secret: str = ""
-    user_id: str = ""
-    username: str = ""
-    # Listener settings
-    watch_tag: str = ""  # only trigger on mentions containing this
-
-
-def _oauth1_header(
-    method: str,
-    url: str,
-    params: Dict[str, str],
-    api_key: str,
-    api_secret: str,
-    access_token: str,
-    access_token_secret: str,
-) -> str:
-    """Build an OAuth 1.0a Authorization header."""
-    oauth_params = {
-        "oauth_consumer_key": api_key,
-        "oauth_nonce": secrets.token_hex(16),
-        "oauth_signature_method": "HMAC-SHA1",
-        "oauth_timestamp": str(int(time.time())),
-        "oauth_token": access_token,
-        "oauth_version": "1.0",
-    }
-
-    # Combine all params for signature base
-    all_params = {**params, **oauth_params}
-    sorted_params = "&".join(
-        f"{urllib.parse.quote(k, safe='')}={urllib.parse.quote(v, safe='')}"
-        for k, v in sorted(all_params.items())
-    )
-
-    base_string = f"{method.upper()}&{urllib.parse.quote(url, safe='')}&{urllib.parse.quote(sorted_params, safe='')}"
-    signing_key = f"{urllib.parse.quote(api_secret, safe='')}&{urllib.parse.quote(access_token_secret, safe='')}"
-
-    import base64
-    signature = base64.b64encode(
-        hmac.new(signing_key.encode(), base_string.encode(), hashlib.sha1).digest()
-    ).decode()
-
-    oauth_params["oauth_signature"] = signature
-
-    header_parts = ", ".join(
-        f'{urllib.parse.quote(k, safe="")}="{urllib.parse.quote(v, safe="")}"'
-        for k, v in sorted(oauth_params.items())
-    )
-    return f"OAuth {header_parts}"
-
-
-@register_client
-class TwitterClient(BasePlatformClient):
-    """Twitter/X platform client with mention polling."""
-
-    PLATFORM_ID = "twitter"
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cred: Optional[TwitterCredential] = None
-        self._poll_task: Optional[asyncio.Task] = None
-        self._since_id: Optional[str] = None
-        self._seen_ids: set = set()
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> TwitterCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, TwitterCredential)
-        if self._cred is None:
-            raise RuntimeError("No Twitter credentials. Use /twitter login first.")
-        return self._cred
-
-    def _auth_header(self, method: str, url: str, params: Optional[Dict[str, str]] = None) -> Dict[str, str]:
-        cred = self._load()
-        return {
-            "Authorization": _oauth1_header(
-                method, url, params or {},
-                cred.api_key, cred.api_secret,
-                cred.access_token, cred.access_token_secret,
-            ),
-        }
-
-    def _bearer_headers(self) -> Dict[str, str]:
-        """Use OAuth 1.0a for all requests since we have user context."""
-        cred = self._load()
-        return {
-            "Content-Type": "application/json",
-        }
-
-    # ------------------------------------------------------------------
-    # BasePlatformClient interface
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Post a tweet (recipient is ignored for tweets, or used as reply_to tweet ID)."""
-        return await self.post_tweet(text, reply_to=recipient if recipient else None)
-
-    # ------------------------------------------------------------------
-    # Watch tag configuration
-    # ------------------------------------------------------------------
-
-    def get_watch_tag(self) -> str:
-        return self._load().watch_tag
-
-    def set_watch_tag(self, tag: str) -> None:
-        cred = self._load()
-        cred.watch_tag = tag.strip()
-        save_credential(CREDENTIAL_FILE, cred)
-        self._cred = cred
-        logger.info(f"[TWITTER] Watch tag set to: {cred.watch_tag or '(disabled)'}")
-
-    # ------------------------------------------------------------------
-    # Listening (mention polling)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        if self._listening:
-            return
-
-        self._message_callback = callback
-        cred = self._load()
-
-        # Verify credentials
-        me = await self.get_me()
-        if "error" in me:
-            raise RuntimeError(f"Invalid Twitter credentials: {me.get('error')}")
-
-        user_data = me.get("result", {})
-        username = user_data.get("username", "unknown")
-        user_id = user_data.get("id", "")
-        logger.info(f"[TWITTER] Authenticated as: @{username}")
-
-        # Save user info
-        if cred.username != username or cred.user_id != user_id:
-            cred.username = username
-            cred.user_id = user_id
-            save_credential(CREDENTIAL_FILE, cred)
-            self._cred = cred
-
-        self._listening = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-
-        tag_info = cred.watch_tag or "(disabled — all mentions)"
-        logger.info(f"[TWITTER] Mention poller started — tag: {tag_info}")
-
-    async def stop_listening(self) -> None:
-        if not self._listening:
-            return
-        self._listening = False
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-        self._poll_task = None
-        logger.info("[TWITTER] Poller stopped")
-
-    async def _poll_loop(self) -> None:
-        # Initial catchup: get latest mention ID without dispatching
-        try:
-            await self._catchup()
-        except Exception as e:
-            logger.warning(f"[TWITTER] Catchup error: {e}")
-
-        while self._listening:
-            try:
-                await self._check_mentions()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error(f"[TWITTER] Poll error: {e}")
-                await asyncio.sleep(RETRY_DELAY)
-                continue
-            await asyncio.sleep(POLL_INTERVAL)
-
-    async def _catchup(self) -> None:
-        """Record the latest mention ID without dispatching."""
-        cred = self._load()
-        if not cred.user_id:
-            return
-
-        url = f"{TWITTER_API}/users/{cred.user_id}/mentions"
-        params = {"max_results": "5", "tweet.fields": "created_at,author_id,text"}
-        auth = self._auth_header("GET", url, params)
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-            if resp.status_code == 200:
-                data = resp.json()
-                tweets = data.get("data", [])
-                if tweets:
-                    self._since_id = tweets[0].get("id")
-                    for t in tweets:
-                        self._seen_ids.add(t.get("id"))
-                    logger.info(f"[TWITTER] Catchup complete — since_id: {self._since_id}")
-
-    async def _check_mentions(self) -> None:
-        cred = self._load()
-        if not cred.user_id:
-            return
-
-        url = f"{TWITTER_API}/users/{cred.user_id}/mentions"
-        params: Dict[str, str] = {
-            "max_results": "20",
-            "tweet.fields": "created_at,author_id,text,in_reply_to_user_id,conversation_id",
-            "expansions": "author_id",
-            "user.fields": "username,name",
-        }
-        if self._since_id:
-            params["since_id"] = self._since_id
-
-        auth = self._auth_header("GET", url, params)
-
-        async with httpx.AsyncClient() as client:
-            resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-
-            if resp.status_code == 429:
-                logger.warning("[TWITTER] Rate limited, backing off")
-                await asyncio.sleep(60)
-                return
-            if resp.status_code != 200:
-                logger.warning(f"[TWITTER] Mentions API error: {resp.status_code} — {resp.text[:200]}")
-                return
-
-            data = resp.json()
-            tweets = data.get("data", [])
-            if not tweets:
-                return
-
-            # Build user lookup
-            includes = data.get("includes", {})
-            users_map = {u["id"]: u for u in includes.get("users", [])}
-
-            # Update since_id to newest
-            self._since_id = tweets[0].get("id")
-
-            for tweet in reversed(tweets):  # oldest first
-                tweet_id = tweet.get("id", "")
-                if tweet_id in self._seen_ids:
-                    continue
-                self._seen_ids.add(tweet_id)
-
-                await self._dispatch_mention(tweet, users_map)
-
-            # Cap seen set
-            if len(self._seen_ids) > 500:
-                self._seen_ids = set(list(self._seen_ids)[-200:])
-
-    async def _dispatch_mention(self, tweet: Dict[str, Any], users_map: Dict[str, Any]) -> None:
-        if not self._message_callback:
-            return
-
-        cred = self._load()
-        text = tweet.get("text", "")
-        author_id = tweet.get("author_id", "")
-        author_info = users_map.get(author_id, {})
-        author_username = author_info.get("username", "")
-        author_name = author_info.get("name", author_username)
-
-        # Watch tag filtering
-        watch_tag = cred.watch_tag
-        if watch_tag:
-            if watch_tag.lower() not in text.lower():
-                return
-            # Extract instruction after the tag
-            tag_lower = watch_tag.lower()
-            idx = text.lower().find(tag_lower)
-            instruction = text[idx + len(watch_tag):].strip() if idx >= 0 else text
-        else:
-            instruction = text
-
-        # Remove @mentions from the start for cleaner instruction
-        clean_instruction = instruction
-        while clean_instruction.startswith("@"):
-            parts = clean_instruction.split(" ", 1)
-            clean_instruction = parts[1].strip() if len(parts) > 1 else ""
-
-        timestamp = None
-        created_at = tweet.get("created_at", "")
-        if created_at:
-            try:
-                timestamp = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
-            except Exception:
-                pass
-
-        platform_msg = PlatformMessage(
-            platform="twitter",
-            sender_id=author_id,
-            sender_name=f"@{author_username}" if author_username else author_name,
-            text=f"@{author_username}: {clean_instruction or text}",
-            channel_id=tweet.get("conversation_id", ""),
-            channel_name="Twitter/X",
-            message_id=tweet.get("id", ""),
-            timestamp=timestamp,
-            raw={
-                "tweet": tweet,
-                "trigger": "mention" if not watch_tag else "mention_tag",
-                "tag": watch_tag,
-                "instruction": clean_instruction or text,
-                "author_username": author_username,
-            },
-        )
-
-        await self._message_callback(platform_msg)
-        logger.info(f"[TWITTER] Mention from @{author_username}: {(clean_instruction or text)[:80]}...")
-
-    # ------------------------------------------------------------------
-    # Twitter API v2 methods
-    # ------------------------------------------------------------------
-
-    async def get_me(self) -> Dict[str, Any]:
-        """Get the authenticated user's info."""
-        url = f"{TWITTER_API}/users/me"
-        params = {"user.fields": "id,name,username,description,public_metrics"}
-        auth = self._auth_header("GET", url, params)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-                if resp.status_code == 200:
-                    data = resp.json().get("data", {})
-                    return {"ok": True, "result": data}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def post_tweet(self, text: str, reply_to: Optional[str] = None) -> Dict[str, Any]:
-        """Post a tweet."""
-        url = f"{TWITTER_API}/tweets"
-        payload: Dict[str, Any] = {"text": text}
-        if reply_to:
-            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
-
-        auth = self._auth_header("POST", url)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(url, headers={**auth, "Content-Type": "application/json"}, json=payload, timeout=15)
-                if resp.status_code in (200, 201):
-                    data = resp.json().get("data", {})
-                    return {"ok": True, "result": {"id": data.get("id"), "text": data.get("text")}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def delete_tweet(self, tweet_id: str) -> Dict[str, Any]:
-        """Delete a tweet."""
-        url = f"{TWITTER_API}/tweets/{tweet_id}"
-        auth = self._auth_header("DELETE", url)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.delete(url, headers={**auth}, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": {"deleted": True}}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_user_timeline(self, user_id: Optional[str] = None, max_results: int = 10) -> Dict[str, Any]:
-        """Get a user's recent tweets."""
-        cred = self._load()
-        uid = user_id or cred.user_id
-        if not uid:
-            return {"error": "No user_id available"}
-
-        url = f"{TWITTER_API}/users/{uid}/tweets"
-        params = {"max_results": str(max_results), "tweet.fields": "created_at,public_metrics,text"}
-        auth = self._auth_header("GET", url, params)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def search_tweets(self, query: str, max_results: int = 10) -> Dict[str, Any]:
-        """Search recent tweets."""
-        url = f"{TWITTER_API}/tweets/search/recent"
-        params = {"query": query, "max_results": str(max_results), "tweet.fields": "created_at,author_id,public_metrics,text", "expansions": "author_id", "user.fields": "username"}
-        auth = self._auth_header("GET", url, params)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json()}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def like_tweet(self, tweet_id: str) -> Dict[str, Any]:
-        """Like a tweet."""
-        cred = self._load()
-        url = f"{TWITTER_API}/users/{cred.user_id}/likes"
-        auth = self._auth_header("POST", url)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(url, headers={**auth, "Content-Type": "application/json"}, json={"tweet_id": tweet_id}, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json().get("data", {})}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def retweet(self, tweet_id: str) -> Dict[str, Any]:
-        """Retweet a tweet."""
-        cred = self._load()
-        url = f"{TWITTER_API}/users/{cred.user_id}/retweets"
-        auth = self._auth_header("POST", url)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.post(url, headers={**auth, "Content-Type": "application/json"}, json={"tweet_id": tweet_id}, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json().get("data", {})}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def get_user_by_username(self, username: str) -> Dict[str, Any]:
-        """Look up a user by username."""
-        url = f"{TWITTER_API}/users/by/username/{username}"
-        params = {"user.fields": "id,name,username,description,public_metrics"}
-        auth = self._auth_header("GET", url, params)
-        try:
-            async with httpx.AsyncClient() as client:
-                resp = await client.get(url, headers={**auth}, params=params, timeout=15)
-                if resp.status_code == 200:
-                    return {"ok": True, "result": resp.json().get("data", {})}
-                return {"error": f"API error: {resp.status_code}", "details": resp.text}
-        except Exception as e:
-            return {"error": str(e)}
-
-    async def reply_to_tweet(self, tweet_id: str, text: str) -> Dict[str, Any]:
-        """Reply to a tweet."""
-        return await self.post_tweet(text, reply_to=tweet_id)
diff --git a/app/external_comms/platforms/whatsapp_bridge/__init__.py b/app/external_comms/platforms/whatsapp_bridge/__init__.py
deleted file mode 100644
index ccf8ab1c..00000000
--- a/app/external_comms/platforms/whatsapp_bridge/__init__.py
+++ /dev/null
@@ -1 +0,0 @@
-# WhatsApp Bridge — Node.js subprocess using whatsapp-web.js
diff --git a/app/external_comms/platforms/whatsapp_business.py b/app/external_comms/platforms/whatsapp_business.py
deleted file mode 100644
index 52057bee..00000000
--- a/app/external_comms/platforms/whatsapp_business.py
+++ /dev/null
@@ -1,172 +0,0 @@
-# -*- coding: utf-8 -*-
-"""WhatsApp Business Cloud API client — direct HTTP via httpx."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from app.external_comms.base import BasePlatformClient
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-GRAPH_API_BASE = "https://graph.facebook.com/v21.0"
-CREDENTIAL_FILE = "whatsapp_business.json"
-
-
-@dataclass
-class WhatsAppBusinessCredential:
-    access_token: str = ""
-    phone_number_id: str = ""
-    app_secret: str = ""
-    verify_token: str = ""
-
-
-@register_client
-class WhatsAppBusinessClient(BasePlatformClient):
-    PLATFORM_ID = "whatsapp_business"
-
-    def __init__(self):
-        super().__init__()
-        self._cred: Optional[WhatsAppBusinessCredential] = None
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> WhatsAppBusinessCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, WhatsAppBusinessCredential)
-        if self._cred is None:
-            raise RuntimeError("No WhatsApp Business credentials. Use /whatsapp-business login first.")
-        return self._cred
-
-    def _headers(self) -> Dict[str, str]:
-        cred = self._load()
-        return {"Authorization": f"Bearer {cred.access_token}", "Content-Type": "application/json"}
-
-    async def connect(self) -> None:
-        self._load()
-        self._connected = True
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a text message via WhatsApp Business Cloud API."""
-        return self.send_text(recipient, text)
-
-    # ------------------------------------------------------------------
-    # Messaging
-    # ------------------------------------------------------------------
-
-    def send_text(self, to: str, text: str) -> Dict[str, Any]:
-        cred = self._load()
-        url = f"{GRAPH_API_BASE}/{cred.phone_number_id}/messages"
-        payload = {
-            "messaging_product": "whatsapp",
-            "to": to,
-            "type": "text",
-            "text": {"body": text},
-        }
-        try:
-            r = httpx.post(url, headers=self._headers(), json=payload, timeout=15)
-            data = r.json()
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def send_template(self, to: str, template_name: str, language_code: str = "en_US",
-                      components: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
-        cred = self._load()
-        url = f"{GRAPH_API_BASE}/{cred.phone_number_id}/messages"
-        template: Dict[str, Any] = {"name": template_name, "language": {"code": language_code}}
-        if components:
-            template["components"] = components
-        payload = {"messaging_product": "whatsapp", "to": to, "type": "template", "template": template}
-        try:
-            r = httpx.post(url, headers=self._headers(), json=payload, timeout=15)
-            data = r.json()
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def send_image(self, to: str, image_url: str, caption: Optional[str] = None) -> Dict[str, Any]:
-        cred = self._load()
-        url = f"{GRAPH_API_BASE}/{cred.phone_number_id}/messages"
-        image: Dict[str, Any] = {"link": image_url}
-        if caption:
-            image["caption"] = caption
-        payload = {"messaging_product": "whatsapp", "to": to, "type": "image", "image": image}
-        try:
-            r = httpx.post(url, headers=self._headers(), json=payload, timeout=15)
-            data = r.json()
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def send_document(self, to: str, document_url: str, filename: Optional[str] = None,
-                      caption: Optional[str] = None) -> Dict[str, Any]:
-        cred = self._load()
-        url = f"{GRAPH_API_BASE}/{cred.phone_number_id}/messages"
-        doc: Dict[str, Any] = {"link": document_url}
-        if filename:
-            doc["filename"] = filename
-        if caption:
-            doc["caption"] = caption
-        payload = {"messaging_product": "whatsapp", "to": to, "type": "document", "document": doc}
-        try:
-            r = httpx.post(url, headers=self._headers(), json=payload, timeout=15)
-            data = r.json()
-            if r.status_code in (200, 201):
-                return {"ok": True, "result": data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    def mark_as_read(self, message_id: str) -> Dict[str, Any]:
-        cred = self._load()
-        url = f"{GRAPH_API_BASE}/{cred.phone_number_id}/messages"
-        payload = {"messaging_product": "whatsapp", "status": "read", "message_id": message_id}
-        try:
-            r = httpx.post(url, headers=self._headers(), json=payload, timeout=15)
-            data = r.json()
-            if r.status_code == 200:
-                return {"ok": True, "result": data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Media
-    # ------------------------------------------------------------------
-
-    def get_media_url(self, media_id: str) -> Dict[str, Any]:
-        try:
-            r = httpx.get(f"{GRAPH_API_BASE}/{media_id}", headers=self._headers(), timeout=15)
-            data = r.json()
-            if r.status_code == 200:
-                return {"ok": True, "result": {"url": data.get("url"), "mime_type": data.get("mime_type"), "file_size": data.get("file_size")}}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
-
-    # ------------------------------------------------------------------
-    # Business Profile
-    # ------------------------------------------------------------------
-
-    def get_business_profile(self) -> Dict[str, Any]:
-        cred = self._load()
-        try:
-            r = httpx.get(f"{GRAPH_API_BASE}/{cred.phone_number_id}/whatsapp_business_profile",
-                          headers=self._headers(), params={"fields": "about,address,description,email,profile_picture_url,websites,vertical"}, timeout=15)
-            data = r.json()
-            if r.status_code == 200:
-                return {"ok": True, "result": data.get("data", [{}])[0] if data.get("data") else data}
-            return {"error": f"API error: {r.status_code}", "details": data}
-        except Exception as e:
-            return {"error": str(e)}
diff --git a/app/external_comms/platforms/whatsapp_web.py b/app/external_comms/platforms/whatsapp_web.py
deleted file mode 100644
index 3ce612c4..00000000
--- a/app/external_comms/platforms/whatsapp_web.py
+++ /dev/null
@@ -1,479 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.platforms.whatsapp_web
-
-WhatsApp Web platform client — uses a Node.js whatsapp-web.js bridge subprocess
-for event-driven messaging (replaces the old Playwright polling approach).
-
-The bridge subprocess is managed by ``WhatsAppBridge`` in
-``app.external_comms.platforms.whatsapp_bridge.client``.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import Any, Dict, List, Optional
-
-from app.external_comms.base import BasePlatformClient, PlatformMessage, MessageCallback
-from app.external_comms.credentials import has_credential, load_credential, save_credential, remove_credential
-from app.external_comms.registry import register_client
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-
-CREDENTIAL_FILE = "whatsapp_web.json"
-
-
-@dataclass
-class WhatsAppWebCredential:
-    session_id: str = ""
-    owner_phone: str = ""
-    owner_name: str = ""
-
-
-# ---------------------------------------------------------------------------
-# Platform client
-# ---------------------------------------------------------------------------
-
-@register_client
-class WhatsAppWebClient(BasePlatformClient):
-    """
-    WhatsApp Web client backed by a whatsapp-web.js Node.js bridge subprocess.
-
-    All messaging and chat operations are delegated to the bridge via
-    JSON-lines IPC (stdin/stdout).
-    """
-
-    PLATFORM_ID = "whatsapp_web"
-
-    def __init__(self) -> None:
-        super().__init__()
-        self._cred: Optional[WhatsAppWebCredential] = None
-        self._bridge = None  # WhatsAppBridge instance (lazy import)
-        self._seen_ids: set = set()  # dedup incoming message IDs
-        self._known_groups: set = set()
-        self._agent_sent_ids: set = set()  # track IDs of messages sent by the agent
-
-    @property
-    def _agent_prefix(self) -> str:
-        """Return prefix like '[AgentName] ' using the configured agent name."""
-        try:
-            from app.onboarding import onboarding_manager
-            name = onboarding_manager.state.agent_name or "AGENT"
-        except Exception:
-            name = "AGENT"
-        return f"[{name}] "
-
-    # ------------------------------------------------------------------
-    # Credential helpers
-    # ------------------------------------------------------------------
-
-    def has_credentials(self) -> bool:
-        return has_credential(CREDENTIAL_FILE)
-
-    def _load(self) -> WhatsAppWebCredential:
-        if self._cred is None:
-            self._cred = load_credential(CREDENTIAL_FILE, WhatsAppWebCredential)
-        if self._cred is None:
-            raise RuntimeError("No WhatsApp Web credentials found. Please log in first.")
-        return self._cred
-
-    @property
-    def owner_phone(self) -> str:
-        """Return the stored owner phone number, or empty string."""
-        return self._load().owner_phone
-
-    # ------------------------------------------------------------------
-    # Bridge access
-    # ------------------------------------------------------------------
-
-    def _get_bridge(self):
-        """Lazily import and return the WhatsAppBridge singleton."""
-        if self._bridge is None:
-            from app.external_comms.platforms.whatsapp_bridge.client import get_whatsapp_bridge
-            self._bridge = get_whatsapp_bridge()
-        return self._bridge
-
-    # ------------------------------------------------------------------
-    # Connection
-    # ------------------------------------------------------------------
-
-    async def connect(self) -> None:
-        """Start the bridge and verify it becomes ready."""
-        bridge = self._get_bridge()
-        if not bridge.is_running:
-            await bridge.start()
-        if not bridge.is_ready:
-            ready = await bridge.wait_for_ready(timeout=120.0)
-            if not ready:
-                raise RuntimeError("WhatsApp bridge did not become ready within timeout")
-        self._connected = True
-
-    async def disconnect(self) -> None:
-        """Stop listening and the bridge subprocess."""
-        await super().disconnect()
-        bridge = self._get_bridge()
-        if bridge.is_running:
-            await bridge.stop()
-
-    # ------------------------------------------------------------------
-    # Messaging
-    # ------------------------------------------------------------------
-
-    # Generic terms the LLM may use to mean "send to the device owner"
-    _OWNER_ALIASES = {"user", "owner", "me", "self"}
-
-    def _resolve_recipient(self, recipient: str) -> str:
-        """If *recipient* is a generic alias like 'user', replace with stored owner phone."""
-        if recipient.strip().lower() in self._OWNER_ALIASES:
-            phone = self.owner_phone
-            if phone:
-                logger.info(f"[WhatsApp Web] Resolved '{recipient}' to owner phone {phone}")
-                return phone
-            logger.warning(f"[WhatsApp Web] Cannot resolve '{recipient}' — owner_phone not stored in credential")
-        return recipient
-
-    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
-        """Send a text message via the bridge. Prepends [AGENT] prefix."""
-        bridge = self._get_bridge()
-        if not bridge.is_ready:
-            return {"status": "error", "error": "Bridge not ready"}
-        resolved = self._resolve_recipient(recipient)
-        prefixed_text = f"{self._agent_prefix}{text}"
-        result = await bridge.send_message(to=resolved, text=prefixed_text)
-        # Track sent message ID to filter echo in _handle_sent_message
-        msg_id = result.get("message_id")
-        if msg_id:
-            self._agent_sent_ids.add(msg_id)
-        return {"status": "success" if result.get("success") else "error", **result}
-
-    async def send_media(
-        self,
-        recipient: str,
-        media_path: str,
-        caption: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Send media is not yet supported via the bridge — send caption as text."""
-        # TODO: Add media support to bridge.js
-        if caption:
-            return await self.send_message(recipient, f"[Media: {media_path}]\n{caption}")
-        return {"status": "error", "error": "Media sending not yet supported via bridge"}
-
-    # ------------------------------------------------------------------
-    # Chat / contact queries
-    # ------------------------------------------------------------------
-
-    async def get_chat_messages(
-        self,
-        phone_number: str,
-        limit: int = 50,
-    ) -> Dict[str, Any]:
-        """Retrieve recent messages from a specific chat."""
-        bridge = self._get_bridge()
-        if not bridge.is_ready:
-            return {"success": False, "error": "Bridge not ready"}
-        result = await bridge.get_chat_messages(chat_id=phone_number, limit=limit)
-        return {"status": "success" if result.get("success") else "error", **result}
-
-    async def get_unread_chats(self) -> Dict[str, Any]:
-        """Return a list of chats with unread messages."""
-        bridge = self._get_bridge()
-        if not bridge.is_ready:
-            return {"success": False, "error": "Bridge not ready"}
-        result = await bridge.get_unread_chats()
-        return {"status": "success" if result.get("success") else "error", **result}
-
-    async def search_contact(self, name: str) -> Dict[str, Any]:
-        """Search contacts by name."""
-        bridge = self._get_bridge()
-        if not bridge.is_ready:
-            return {"success": False, "error": "Bridge not ready"}
-        result = await bridge.search_contact(name=name)
-        return {"status": "success" if result.get("success") else "error", **result}
-
-    async def get_session_status(self) -> Optional[Dict[str, Any]]:
-        """Get bridge/client status."""
-        bridge = self._get_bridge()
-        if not bridge.is_running:
-            return {"status": "disconnected", "ready": False}
-        try:
-            result = await bridge.get_status()
-            return {"status": "connected" if result.get("ready") else "waiting", **result}
-        except Exception:
-            return {"status": "disconnected", "ready": False}
-
-    # ------------------------------------------------------------------
-    # Listening (event-driven via bridge callback)
-    # ------------------------------------------------------------------
-
-    @property
-    def supports_listening(self) -> bool:
-        return True
-
-    async def start_listening(self, callback: MessageCallback) -> None:
-        """Start the bridge and register for incoming message events."""
-        if self._listening:
-            return
-
-        # Invalidate cached credential so we pick up the latest
-        self._cred = None
-
-        bridge = self._get_bridge()
-
-        # If bridge is already running and ready (from login flow), reuse it
-        logger.info(f"[WhatsApp Web] Bridge state check: is_running={bridge.is_running}, is_ready={bridge.is_ready}")
-        if bridge.is_running and bridge.is_ready:
-            logger.info("[WhatsApp Web] Bridge already running and ready, reusing...")
-            bridge.set_event_callback(self._on_bridge_event)
-            event_type = "ready"
-        else:
-            # Restart bridge fresh
-            if bridge.is_running:
-                logger.info("[WhatsApp Web] Restarting bridge on current event loop...")
-                await bridge.stop()
-                # Give wwebjs time to save session files
-                import asyncio
-                await asyncio.sleep(2)
-
-            await bridge.start()
-
-            # Register event callback
-            bridge.set_event_callback(self._on_bridge_event)
-
-            # Wait for ready or QR — if QR is needed the user must login first
-            logger.info("[WhatsApp Web] Waiting for bridge to become ready...")
-            event_type, _ = await bridge.wait_for_qr_or_ready(timeout=90.0)
-
-        if event_type == "qr":
-            # Not authenticated — stop the bridge quietly (user will connect via settings UI)
-            logger.info("[WhatsApp Web] Session expired or not authenticated — connect via settings to scan QR")
-            bridge.set_event_callback(None)
-            await bridge.stop()
-            return  # Don't raise — just skip silently
-
-        if event_type != "ready":
-            bridge.set_event_callback(None)
-            raise RuntimeError("WhatsApp bridge did not become ready — timed out")
-
-        # Update credential with owner info from the bridge
-        if bridge.owner_phone or bridge.owner_name:
-            cred = self._load()
-            if cred.owner_phone != bridge.owner_phone or cred.owner_name != bridge.owner_name:
-                updated = WhatsAppWebCredential(
-                    session_id=cred.session_id,
-                    owner_phone=bridge.owner_phone or cred.owner_phone,
-                    owner_name=bridge.owner_name or cred.owner_name,
-                )
-                save_credential(CREDENTIAL_FILE, updated)
-                self._cred = updated
-                logger.info(
-                    f"[WhatsApp Web] Updated credential: phone={updated.owner_phone}, "
-                    f"name={updated.owner_name}"
-                )
-
-        self._message_callback = callback
-        self._listening = True
-        self._connected = True
-        logger.info(
-            f"[WhatsApp Web] Listener started — connected as "
-            f"+{bridge.owner_phone} ({bridge.owner_name})"
-        )
-
-    async def stop_listening(self) -> None:
-        """Stop listening for messages."""
-        if not self._listening:
-            return
-
-        self._listening = False
-
-        bridge = self._get_bridge()
-        bridge.set_event_callback(None)
-
-        logger.info("[WhatsApp Web] Listener stopped")
-
-    # -- Bridge event handler ------------------------------------------------
-
-    async def _on_bridge_event(self, event: str, data: Dict[str, Any]) -> None:
-        """Handle events from the bridge subprocess."""
-        if event == "message":
-            await self._handle_incoming_message(data)
-        elif event == "message_sent":
-            await self._handle_sent_message(data)
-        elif event == "disconnected":
-            self._connected = False
-            logger.warning(f"[WhatsApp Web] Disconnected: {data.get('reason', 'unknown')}")
-        elif event == "ready":
-            self._connected = True
-
-    async def _handle_incoming_message(self, data: Dict[str, Any]) -> None:
-        """Process an incoming message event from the bridge."""
-        if not self._listening or not self._message_callback:
-            return
-
-        msg_id = data.get("id", "")
-        if msg_id in self._seen_ids:
-            return
-        self._seen_ids.add(msg_id)
-
-        # Skip messages from self (handled by message_sent event)
-        if data.get("from_me", False):
-            return
-
-        body = data.get("body", "")
-        if not body:
-            return
-
-        chat = data.get("chat", {})
-        contact = data.get("contact", {})
-        is_group = chat.get("is_group", False)
-        is_muted = chat.get("is_muted", False)
-
-        # Track known groups
-        chat_name = chat.get("name", "")
-        if is_group:
-            self._known_groups.add(chat_name)
-
-        # Skip muted group chats
-        if is_muted and is_group:
-            logger.debug(f"[WhatsApp Web] Skipping muted group: {chat_name}")
-            return
-
-        # In group chats, only process messages that @mention the user
-        if is_group:
-            if not self._is_mention_for_me(body):
-                return
-
-        sender_name = contact.get("name", "") or chat_name
-        sender_id = data.get("from", "")
-        timestamp = data.get("timestamp")
-
-        ts: Optional[datetime] = None
-        if timestamp:
-            try:
-                ts = datetime.fromtimestamp(timestamp, tz=timezone.utc)
-            except Exception:
-                ts = datetime.now(tz=timezone.utc)
-
-        platform_msg = PlatformMessage(
-            platform=self.PLATFORM_ID,
-            sender_id=sender_id,
-            sender_name=sender_name,
-            text=body,
-            channel_id=chat.get("id", ""),
-            channel_name=chat_name,
-            message_id=msg_id,
-            timestamp=ts,
-            raw={
-                "source": "WhatsApp Web",
-                "integrationType": "whatsapp_web",
-                "is_self_message": False,
-                "is_group": is_group,
-                "contactId": sender_id,
-                "contactName": sender_name,
-                "messageBody": body,
-                "chatId": chat.get("id", ""),
-                "chatName": chat_name,
-                "timestamp": str(timestamp or ""),
-            },
-        )
-
-        await self._message_callback(platform_msg)
-        logger.info(f"[WhatsApp Web] Dispatched message from {sender_name} in {chat_name}: {body[:50]}...")
-
-    async def _handle_sent_message(self, data: Dict[str, Any]) -> None:
-        """Process a message sent by the user from another device (self-chat or outgoing)."""
-        if not self._listening or not self._message_callback:
-            return
-
-        # Only dispatch self-chat messages (messages to yourself)
-        if not data.get("is_self_chat", False):
-            return
-
-        msg_id = data.get("id", "")
-        if msg_id in self._seen_ids:
-            return
-        self._seen_ids.add(msg_id)
-
-        # Skip messages sent by the agent (prevents echo loop)
-        if msg_id and msg_id in self._agent_sent_ids:
-            self._agent_sent_ids.discard(msg_id)
-            logger.debug(f"[WhatsApp Web] Skipping agent-sent message (ID match): {msg_id}")
-            return
-
-        body = data.get("body", "")
-        if not body:
-            return
-
-        # Also skip by prefix in case of race condition (ID not yet tracked)
-        if body.startswith(self._agent_prefix):
-            logger.debug(f"[WhatsApp Web] Skipping agent-sent message (prefix match): {body[:50]}...")
-            return
-
-        chat = data.get("chat", {})
-        chat_name = chat.get("name", "")
-        timestamp = data.get("timestamp")
-
-        ts: Optional[datetime] = None
-        if timestamp:
-            try:
-                ts = datetime.fromtimestamp(timestamp, tz=timezone.utc)
-            except Exception:
-                ts = datetime.now(tz=timezone.utc)
-
-        platform_msg = PlatformMessage(
-            platform=self.PLATFORM_ID,
-            sender_id=data.get("from", ""),
-            sender_name=chat_name or "Self",
-            text=body,
-            channel_id=chat.get("id", ""),
-            channel_name=chat_name,
-            message_id=msg_id,
-            timestamp=ts,
-            raw={
-                "source": "WhatsApp Web",
-                "integrationType": "whatsapp_web",
-                "is_self_message": True,
-                "is_group": False,
-                "contactId": data.get("from", ""),
-                "contactName": chat_name or "Self",
-                "messageBody": body,
-                "chatId": chat.get("id", ""),
-                "chatName": chat_name,
-                "timestamp": str(timestamp or ""),
-            },
-        )
-
-        await self._message_callback(platform_msg)
-        logger.info(f"[WhatsApp Web] Dispatched self-message: {body[:50]}...")
-
-    # -- @mention helper ---------------------------------------------------
-
-    def _is_mention_for_me(self, text: str) -> bool:
-        """Check whether *text* contains an @mention directed at the logged-in user."""
-        if "@" not in text:
-            return False
-
-        text_lower = text.lower()
-
-        # Use owner_name from bridge
-        bridge = self._get_bridge()
-        own_name = bridge.owner_name if bridge else ""
-
-        if own_name:
-            own_lower = own_name.lower()
-            if f"@{own_lower}" in text_lower:
-                return True
-            first_name = own_lower.split()[0] if " " in own_lower else ""
-            if first_name and f"@{first_name}" in text_lower:
-                return True
-            return False
-
-        # Fallback: no own name known — treat any @mention as potentially ours
-        return True
diff --git a/app/external_comms/platforms/whatsapp_web_helpers.py b/app/external_comms/platforms/whatsapp_web_helpers.py
deleted file mode 100644
index c74fa9b9..00000000
--- a/app/external_comms/platforms/whatsapp_web_helpers.py
+++ /dev/null
@@ -1,2195 +0,0 @@
-"""
-WhatsApp Web helpers using Playwright (headless Chrome) for connecting any WhatsApp number via QR code.
-
-This module provides functionality for:
-- Starting WhatsApp Web sessions in headless Chrome
-- Capturing QR codes for pairing
-- Sending/receiving messages via WhatsApp Web
-- Managing session persistence
-
-Dependencies:
-    pip install playwright
-    playwright install chromium
-
-Note: This is for personal WhatsApp accounts. For business use, prefer the WhatsApp Business API.
-"""
-
-import asyncio
-import base64
-import json
-import os
-import re
-from dataclasses import dataclass
-from difflib import SequenceMatcher
-from pathlib import Path
-from typing import Callable, Dict, List, Optional, Any, Tuple
-from datetime import datetime
-
-from agent_core.utils.logger import logger
-
-
-def _normalize_name(name: str) -> str:
-    """Normalize a name for comparison: lowercase, remove extra spaces, strip punctuation."""
-    # Lowercase and strip
-    name = name.lower().strip()
-    # Remove common punctuation but keep spaces
-    name = re.sub(r'[^\w\s]', '', name)
-    # Collapse multiple spaces
-    name = re.sub(r'\s+', ' ', name)
-    return name
-
-
-def _get_name_words(name: str) -> List[str]:
-    """Get normalized words from a name."""
-    return _normalize_name(name).split()
-
-
-def _fuzzy_name_match(search_query: str, contact_name: str, threshold: float = 0.7) -> Tuple[bool, float]:
-    """
-    Check if a search query fuzzy-matches a contact name.
-
-    Returns (is_match, score) where:
-    - is_match: True if the names are similar enough
-    - score: Similarity score between 0 and 1
-
-    Matching logic:
-    1. If all search words are contained in the contact name (substring match), it's a match
-    2. Otherwise, use sequence similarity with typo tolerance
-
-    Examples:
-    - "Emad Tavana" matches "Emad Tavana MDX" (all words contained) -> True, ~0.9
-    - "Emad tavana" matches "Emad Tavana MDX" (case insensitive) -> True, ~0.9
-    - "Emad Tavana" does NOT match "Emad Davane" (Tavana != Davane) -> False, ~0.6
-    """
-    search_words = _get_name_words(search_query)
-    contact_words = _get_name_words(contact_name)
-
-    if not search_words or not contact_words:
-        return False, 0.0
-
-    # Strategy 1: Check if all search words are contained in contact words
-    # This handles "Emad Tavana" -> "Emad Tavana MDX"
-    all_words_found = True
-    word_match_scores = []
-
-    for search_word in search_words:
-        # Find the best matching word in contact
-        best_word_score = 0.0
-        for contact_word in contact_words:
-            # Exact match
-            if search_word == contact_word:
-                best_word_score = 1.0
-                break
-            # Substring match (e.g., "tav" in "tavana")
-            if search_word in contact_word or contact_word in search_word:
-                score = min(len(search_word), len(contact_word)) / max(len(search_word), len(contact_word))
-                best_word_score = max(best_word_score, score)
-            # Fuzzy word match for typos
-            else:
-                ratio = SequenceMatcher(None, search_word, contact_word).ratio()
-                best_word_score = max(best_word_score, ratio)
-
-        word_match_scores.append(best_word_score)
-        # A word is "found" if it matches well enough (>= 0.8 for individual words)
-        if best_word_score < 0.8:
-            all_words_found = False
-
-    # Calculate overall score
-    if word_match_scores:
-        avg_word_score = sum(word_match_scores) / len(word_match_scores)
-    else:
-        avg_word_score = 0.0
-
-    # Also calculate full string similarity as a secondary metric
-    full_similarity = SequenceMatcher(
-        None,
-        _normalize_name(search_query),
-        _normalize_name(contact_name)
-    ).ratio()
-
-    # Combined score: weight word matching higher
-    combined_score = (avg_word_score * 0.7) + (full_similarity * 0.3)
-
-    # It's a match if:
-    # 1. All search words were found in the contact name, OR
-    # 2. The combined score is above threshold
-    is_match = all_words_found or combined_score >= threshold
-
-    return is_match, combined_score
-
-# Session storage directory
-WHATSAPP_WEB_SESSIONS_DIR = Path(__file__).parent.parent.parent.parent.parent / ".whatsapp_web_sessions"
-
-
-@dataclass
-class WhatsAppWebSession:
-    """Represents an active WhatsApp Web session."""
-    session_id: str
-    user_id: str
-    jid: Optional[str] = None
-    phone_number: Optional[str] = None
-    display_name: Optional[str] = None
-    status: str = "initializing"  # initializing, qr_ready, connected, disconnected, error
-    qr_code: Optional[str] = None
-    created_at: Optional[datetime] = None
-    last_activity: Optional[datetime] = None
-
-
-class WhatsAppWebManager:
-    """
-    Manages WhatsApp Web sessions using Playwright (headless Chrome).
-
-    Usage:
-        manager = WhatsAppWebManager()
-        session = await manager.create_session(user_id="user123")
-        # QR code will be available in session.qr_code
-        # Poll session.status until "connected"
-    """
-
-    def __init__(self):
-        self._sessions: Dict[str, WhatsAppWebSession] = {}
-        self._browsers: Dict[str, Any] = {}  # session_id -> browser
-        self._pages: Dict[str, Any] = {}  # session_id -> page
-        self._chat_previews: Dict[str, str] = {}  # chat_name -> last seen preview text
-        self._playwright_loop: Optional[asyncio.AbstractEventLoop] = None  # loop where Playwright was started
-        self._ensure_sessions_dir()
-
-    async def run_on_playwright_loop(self, coro):
-        """Run a coroutine on the event loop where Playwright was started.
-
-        When Playwright is started on the main event loop and actions are executed
-        on worker threads (each with their own event loop), Playwright calls fail
-        with "The future belongs to a different loop". This method dispatches the
-        coroutine to the correct loop using run_coroutine_threadsafe.
-
-        If we're already on the Playwright loop (or no loop was recorded), the
-        coroutine is awaited directly.
-        """
-        import concurrent.futures
-
-        if self._playwright_loop is None:
-            return await coro
-
-        try:
-            current_loop = asyncio.get_running_loop()
-        except RuntimeError:
-            current_loop = None
-
-        if current_loop is self._playwright_loop:
-            return await coro
-
-        # We're on a different loop — dispatch to the Playwright loop
-        future = asyncio.run_coroutine_threadsafe(coro, self._playwright_loop)
-        # Block the current thread until the result is ready (with timeout)
-        return future.result(timeout=120)
-
-    def _ensure_sessions_dir(self):
-        """Create sessions directory if it doesn't exist."""
-        WHATSAPP_WEB_SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
-
-    def _get_session_path(self, session_id: str) -> Path:
-        """Get the path for session data storage (browser profile)."""
-        return WHATSAPP_WEB_SESSIONS_DIR / session_id
-
-    async def create_session(
-        self,
-        user_id: str,
-        session_id: Optional[str] = None,
-        on_qr_code: Optional[Callable[[str], None]] = None,
-        on_connected: Optional[Callable[[str, str], None]] = None,
-        on_disconnected: Optional[Callable[[], None]] = None,
-    ) -> WhatsAppWebSession:
-        """
-        Create a new WhatsApp Web session using Playwright.
-
-        Args:
-            user_id: The user ID to associate with this session
-            session_id: Optional session ID (generated if not provided)
-            on_qr_code: Callback when QR code is available (receives base64 QR image)
-            on_connected: Callback when connected (receives JID and phone number)
-            on_disconnected: Callback when disconnected
-
-        Returns:
-            WhatsAppWebSession object with status and QR code info
-        """
-        import uuid
-
-        if session_id is None:
-            session_id = str(uuid.uuid4())
-
-        session = WhatsAppWebSession(
-            session_id=session_id,
-            user_id=user_id,
-            status="initializing",
-            created_at=datetime.utcnow(),
-        )
-        self._sessions[session_id] = session
-
-        try:
-            from playwright.async_api import async_playwright
-
-            logger.info(f"[WhatsApp Web] Starting Playwright session {session_id}")
-
-            # Start browser with persistent context for session storage
-            session_path = str(self._get_session_path(session_id))
-
-            playwright = await async_playwright().start()
-            self._playwright_loop = asyncio.get_running_loop()
-
-            # Use headless=False for debugging, or "new" headless mode which is less detectable
-            # WhatsApp Web may block old headless mode
-            browser = await playwright.chromium.launch_persistent_context(
-                user_data_dir=session_path,
-                headless=True,
-                args=[
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    '--disable-dev-shm-usage',
-                    '--disable-accelerated-2d-canvas',
-                    '--no-first-run',
-                    '--no-zygote',
-                    '--disable-gpu',
-                    '--disable-blink-features=AutomationControlled',  # Avoid detection
-                ],
-                user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
-                viewport={'width': 1280, 'height': 800},
-                locale='en-US',
-            )
-
-            self._browsers[session_id] = (playwright, browser)
-
-            # Get the default page or create new one
-            pages = browser.pages
-            if pages:
-                page = pages[0]
-            else:
-                page = await browser.new_page()
-            self._pages[session_id] = page
-
-            # Navigate to WhatsApp Web
-            logger.info(f"[WhatsApp Web] Navigating to WhatsApp Web for session {session_id}")
-            await page.goto('https://web.whatsapp.com', wait_until='domcontentloaded', timeout=60000)
-
-            # Start background task to monitor for QR code and connection
-            asyncio.create_task(self._monitor_session(session_id, session, on_qr_code, on_connected, on_disconnected))
-
-            return session
-
-        except ImportError as e:
-            logger.error(f"[WhatsApp Web] Playwright not installed: {e}")
-            logger.warning("[WhatsApp Web] Install with: pip install playwright && playwright install chromium")
-            session.status = "error"
-            session.qr_code = None
-            return session
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to create session: {e}", exc_info=True)
-            session.status = "error"
-            return session
-
-    async def _monitor_session(
-        self,
-        session_id: str,
-        session: WhatsAppWebSession,
-        on_qr_code: Optional[Callable],
-        on_connected: Optional[Callable],
-        on_disconnected: Optional[Callable],
-    ):
-        """Monitor the WhatsApp Web page for QR code and connection status."""
-        logger.info(f"[WhatsApp Web] Starting monitor task for session {session_id}")
-
-        page = self._pages.get(session_id)
-        if not page:
-            logger.error(f"[WhatsApp Web] No page found for session {session_id}")
-            session.status = "error"
-            return
-
-        qr_captured = False
-        max_attempts = 60  # 2 minutes timeout (2 sec intervals)
-        attempts = 0
-
-        # Wait for page to fully load first
-        try:
-            logger.info(f"[WhatsApp Web] Waiting for page to load for session {session_id}")
-            await page.wait_for_load_state('networkidle', timeout=30000)
-            logger.info(f"[WhatsApp Web] Page loaded for session {session_id}")
-
-            # Give WhatsApp Web extra time to render QR code
-            await asyncio.sleep(3)
-        except Exception as e:
-            logger.warning(f"[WhatsApp Web] Page load wait timed out: {e}")
-
-        while attempts < max_attempts and session_id in self._sessions:
-            try:
-                attempts += 1
-
-                if attempts % 5 == 1:
-                    logger.info(f"[WhatsApp Web] Monitor attempt {attempts} for session {session_id}, current status: {session.status}")
-
-                # Check if already logged in (main chat interface visible)
-                is_logged_in = await page.locator('[data-testid="chat-list"]').count() > 0
-                if not is_logged_in:
-                    # Alternative selectors for logged-in state
-                    is_logged_in = await page.locator('div[data-tab="3"]').count() > 0
-                if not is_logged_in:
-                    # Another alternative - side panel
-                    is_logged_in = await page.locator('#side').count() > 0
-
-                if is_logged_in:
-                    session.last_activity = datetime.utcnow()
-                    logger.info(f"[WhatsApp Web] Session {session_id} logged in, extracting owner info...")
-
-                    # Extract owner phone + name via JS (retry up to 3 times)
-                    # NOTE: status is set to "connected" AFTER extraction so that
-                    # callers waiting on status don't race ahead and kill the browser.
-                    for _attempt in range(3):
-                        try:
-                            info = await page.evaluate("""() => {
-                                try {
-                                    let phone = '';
-
-                                    // 1. localStorage "last-wid-md" — most reliable source
-                                    //    Format: '"447417378160:3@c.us"' or '"923164706597@c.us"'
-                                    for (const key of ['last-wid-md', 'last-wid']) {
-                                        const raw = localStorage.getItem(key);
-                                        if (raw) {
-                                            // Strip quotes, then extract digits before @, :, or end
-                                            const cleaned = raw.replace(/"/g, '');
-                                            const match = cleaned.match(/^(\\d+)/);
-                                            if (match) { phone = match[1]; break; }
-                                        }
-                                    }
-
-                                    // 2. WhatsApp internal store (may not be available)
-                                    if (!phone) {
-                                        const storePaths = [
-                                            () => window.Store && window.Store.Conn && window.Store.Conn.wid && window.Store.Conn.wid.user,
-                                            () => window.Store && window.Store.Conn && window.Store.Conn.wid && window.Store.Conn.wid._serialized,
-                                        ];
-                                        for (const fn of storePaths) {
-                                            try {
-                                                const v = fn();
-                                                if (v) {
-                                                    const m = String(v).match(/^(\\d+)/);
-                                                    if (m) { phone = m[1]; break; }
-                                                }
-                                            } catch {}
-                                        }
-                                    }
-
-                                    // 3. Display name from DOM
-                                    let name = '';
-                                    const avatar = document.querySelector('header img[alt]');
-                                    if (avatar) {
-                                        const alt = avatar.getAttribute('alt');
-                                        if (alt && alt.length > 0) name = alt;
-                                    }
-                                    if (!name) {
-                                        const span = document.querySelector('header span[title]');
-                                        if (span) name = span.getAttribute('title') || '';
-                                    }
-
-                                    return { phone, name };
-                                } catch (err) {
-                                    return { phone: '', name: '', error: err.message };
-                                }
-                            }""")
-
-                            phone = (info or {}).get("phone", "")
-                            name = (info or {}).get("name", "")
-
-                            if phone:
-                                session.phone_number = phone
-                                session.jid = f"{phone.replace('+', '').replace(' ', '')}@s.whatsapp.net"
-                                logger.info(f"[WhatsApp Web] Owner phone extracted: {phone}")
-                            if name:
-                                session.display_name = name
-                                logger.info(f"[WhatsApp Web] Owner name extracted: {name}")
-
-                            if phone:
-                                break  # Got what we need
-                        except Exception as e:
-                            logger.debug(f"[WhatsApp Web] Owner info extraction attempt {_attempt + 1} failed: {e}")
-
-                        if _attempt < 2:
-                            await asyncio.sleep(2)
-                    else:
-                        if not session.phone_number:
-                            logger.warning(f"[WhatsApp Web] Could not extract owner phone after 3 attempts for session {session_id}")
-
-                    # Now mark as connected — callers polling on status can proceed
-                    session.status = "connected"
-                    logger.info(f"[WhatsApp Web] Session {session_id} connected! phone={session.phone_number or 'N/A'}, name={session.display_name or 'N/A'}")
-
-                    if on_connected:
-                        on_connected(session.jid or "", session.phone_number or "")
-                    return
-
-                # Try multiple QR code selectors
-                qr_selectors = [
-                    'canvas[aria-label="Scan this QR code to link a device!"]',
-                    'canvas[aria-label*="QR"]',
-                    'canvas[aria-label*="qr"]',
-                    '[data-testid="qrcode"]',
-                    'div[data-ref] canvas',  # WhatsApp uses data-ref for QR container
-                    'canvas',  # Last resort - any canvas
-                ]
-
-                qr_found = False
-                for selector in qr_selectors:
-                    try:
-                        qr_elem = page.locator(selector).first
-                        if await qr_elem.count() > 0:
-                            # Make sure it's visible and has reasonable size
-                            box = await qr_elem.bounding_box()
-                            if box and box['width'] > 50 and box['height'] > 50:
-                                qr_screenshot = await qr_elem.screenshot()
-                                qr_base64 = f"data:image/png;base64,{base64.b64encode(qr_screenshot).decode()}"
-
-                                session.qr_code = qr_base64
-                                session.status = "qr_ready"
-                                qr_found = True
-
-                                if not qr_captured:
-                                    logger.info(f"[WhatsApp Web] QR code captured for session {session_id} using selector: {selector}")
-                                    qr_captured = True
-                                    if on_qr_code:
-                                        on_qr_code(qr_base64)
-                                break
-                    except Exception as e:
-                        continue
-
-                # Log page state for debugging if no QR found after several attempts
-                if not qr_found and attempts == 5:
-                    try:
-                        page_title = await page.title()
-                        page_url = page.url
-                        logger.info(f"[WhatsApp Web] Page state - title: {page_title}, url: {page_url}")
-
-                        # Check for loading indicator
-                        loading = await page.locator('[data-testid="startup"]').count()
-                        if loading > 0:
-                            logger.info(f"[WhatsApp Web] WhatsApp is still loading...")
-                    except Exception as e:
-                        logger.debug(f"[WhatsApp Web] Could not get page state: {e}")
-
-                await asyncio.sleep(2)
-
-            except Exception as e:
-                logger.error(f"[WhatsApp Web] Error monitoring session {session_id}: {e}", exc_info=True)
-                await asyncio.sleep(2)
-
-        # Timeout reached
-        if session.status != "connected":
-            session.status = "error"
-            logger.warning(f"[WhatsApp Web] Session {session_id} timed out waiting for QR scan")
-
-    def get_session(self, session_id: str) -> Optional[WhatsAppWebSession]:
-        """Get session by ID."""
-        return self._sessions.get(session_id)
-
-    def get_user_sessions(self, user_id: str) -> List[WhatsAppWebSession]:
-        """Get all sessions for a user."""
-        return [s for s in self._sessions.values() if s.user_id == user_id]
-
-    async def disconnect_session(self, session_id: str) -> bool:
-        """Disconnect and remove a session."""
-        # Close browser
-        if session_id in self._browsers:
-            try:
-                playwright, browser = self._browsers[session_id]
-                await browser.close()
-                await playwright.stop()
-            except Exception as e:
-                logger.error(f"[WhatsApp Web] Error closing browser for session {session_id}: {e}")
-            del self._browsers[session_id]
-
-        if session_id in self._pages:
-            del self._pages[session_id]
-
-        if session_id in self._sessions:
-            del self._sessions[session_id]
-
-        # Optionally remove session data directory
-        # session_path = self._get_session_path(session_id)
-        # if session_path.exists():
-        #     import shutil
-        #     shutil.rmtree(session_path)
-
-        return True
-
-    def list_persisted_sessions(self) -> List[Dict[str, Any]]:
-        """List all sessions that have persisted data on disk (can be reconnected)."""
-        sessions = []
-        if WHATSAPP_WEB_SESSIONS_DIR.exists():
-            for session_dir in WHATSAPP_WEB_SESSIONS_DIR.iterdir():
-                if session_dir.is_dir():
-                    sessions.append({
-                        "session_id": session_dir.name,
-                        "path": str(session_dir),
-                        "is_active": session_dir.name in self._sessions,
-                    })
-        return sessions
-
-    async def reconnect_session(
-        self,
-        session_id: str,
-        user_id: str,
-        on_connected: Optional[Callable[[str, str], None]] = None,
-        on_disconnected: Optional[Callable[[], None]] = None,
-    ) -> Dict[str, Any]:
-        """
-        Reconnect to an existing WhatsApp Web session using persisted browser data.
-
-        This is useful after agent restart when the WhatsApp link is still active
-        on the phone but the browser session was lost.
-
-        Args:
-            session_id: The session ID to reconnect (must have data on disk)
-            user_id: The user ID to associate with this session
-            on_connected: Callback when connected
-            on_disconnected: Callback when disconnected
-
-        Returns:
-            Dict with status and session info
-        """
-        session_path = self._get_session_path(session_id)
-
-        if not session_path.exists():
-            return {
-                "success": False,
-                "error": f"No persisted session data found for session_id: {session_id}",
-                "hint": "Use start_session to create a new session with QR code"
-            }
-
-        # Check if already active
-        if session_id in self._sessions:
-            session = self._sessions[session_id]
-            return {
-                "success": True,
-                "status": session.status,
-                "session_id": session_id,
-                "message": "Session already active"
-            }
-
-        try:
-            from playwright.async_api import async_playwright
-
-            logger.info(f"[WhatsApp Web] Reconnecting session {session_id} from persisted data")
-
-            # Create session object
-            session = WhatsAppWebSession(
-                session_id=session_id,
-                user_id=user_id,
-                status="reconnecting",
-                created_at=datetime.utcnow(),
-            )
-            self._sessions[session_id] = session
-
-            # Launch browser with existing profile
-            playwright = await async_playwright().start()
-            self._playwright_loop = asyncio.get_running_loop()
-            browser = await playwright.chromium.launch_persistent_context(
-                user_data_dir=str(session_path),
-                headless=True,
-                args=[
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    '--disable-dev-shm-usage',
-                    '--disable-accelerated-2d-canvas',
-                    '--no-first-run',
-                    '--no-zygote',
-                    '--disable-gpu',
-                    '--disable-blink-features=AutomationControlled',
-                ],
-                user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
-                viewport={'width': 1280, 'height': 800},
-                locale='en-US',
-            )
-
-            self._browsers[session_id] = (playwright, browser)
-
-            # Get page
-            pages = browser.pages
-            if pages:
-                page = pages[0]
-            else:
-                page = await browser.new_page()
-            self._pages[session_id] = page
-
-            # Navigate to WhatsApp Web
-            logger.info(f"[WhatsApp Web] Navigating to WhatsApp Web for reconnect...")
-            await page.goto('https://web.whatsapp.com', wait_until='domcontentloaded', timeout=60000)
-            await page.wait_for_load_state('networkidle', timeout=30000)
-
-            # Wait for page to stabilize
-            await asyncio.sleep(3)
-
-            # Check if already logged in
-            logged_in_selectors = [
-                '[data-testid="chat-list"]',
-                'div[data-tab="3"]',
-                '#side',
-            ]
-
-            is_logged_in = False
-            for selector in logged_in_selectors:
-                try:
-                    if await page.locator(selector).count() > 0:
-                        is_logged_in = True
-                        break
-                except Exception:
-                    continue
-
-            if is_logged_in:
-                session.status = "connected"
-                session.last_activity = datetime.utcnow()
-                logger.info(f"[WhatsApp Web] Session {session_id} reconnected successfully!")
-
-                if on_connected:
-                    on_connected(session.jid or "", session.phone_number or "")
-
-                return {
-                    "success": True,
-                    "status": "connected",
-                    "session_id": session_id,
-                    "message": "Successfully reconnected to existing WhatsApp Web session"
-                }
-            else:
-                # Check if QR code is shown (session expired on phone)
-                qr_selectors = [
-                    'canvas[aria-label="Scan this QR code to link a device!"]',
-                    'canvas[aria-label*="QR"]',
-                    '[data-testid="qrcode"]',
-                ]
-
-                needs_qr = False
-                for selector in qr_selectors:
-                    try:
-                        if await page.locator(selector).count() > 0:
-                            needs_qr = True
-                            break
-                    except Exception:
-                        continue
-
-                if needs_qr:
-                    session.status = "qr_required"
-                    logger.warning(f"[WhatsApp Web] Session {session_id} requires new QR scan (link expired on phone)")
-                    return {
-                        "success": False,
-                        "status": "qr_required",
-                        "session_id": session_id,
-                        "error": "WhatsApp Web session expired. The device was unlinked from your phone.",
-                        "hint": "Go to WhatsApp > Linked Devices on your phone and check if this device is still linked. If not, start a new session."
-                    }
-                else:
-                    session.status = "unknown"
-                    return {
-                        "success": False,
-                        "status": "unknown",
-                        "session_id": session_id,
-                        "error": "Could not determine session state. WhatsApp Web may still be loading."
-                    }
-
-        except ImportError as e:
-            logger.error(f"[WhatsApp Web] Playwright not installed: {e}")
-            return {"success": False, "error": "Playwright not installed. Run: pip install playwright && playwright install chromium"}
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to reconnect session: {e}", exc_info=True)
-            # Clean up on failure
-            if session_id in self._sessions:
-                del self._sessions[session_id]
-            if session_id in self._browsers:
-                try:
-                    playwright, browser = self._browsers[session_id]
-                    await browser.close()
-                    await playwright.stop()
-                except Exception:
-                    pass
-                del self._browsers[session_id]
-            if session_id in self._pages:
-                del self._pages[session_id]
-            return {"success": False, "error": str(e)}
-
-    async def send_message(
-        self,
-        session_id: str,
-        to: str,
-        message: str,
-    ) -> Dict[str, Any]:
-        """
-        Send a text message via WhatsApp Web.
-
-        Args:
-            session_id: The session ID to use
-            to: Recipient phone number (with country code, e.g., "1234567890") or contact name
-            message: The message text
-
-        Returns:
-            Dict with message ID and status
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # 1. Resolve contact if 'to' contains letters
-            import re
-            if re.search(r'[a-zA-Z]', to):
-                logger.info(f"[WhatsApp Web] Resolving contact name '{to}' inside send_message...")
-                res = await self.resolve_contact_phone(session_id, to)
-                if res.get("success"):
-                    to = res.get("phone")
-                    logger.info(f"[WhatsApp Web] Resolved to {to}")
-                else:
-                    return {"success": False, "error": f"Could not resolve contact '{to}': {res.get('error')}"}
-
-            # Clean phone number
-            phone = to.lstrip('+').replace(' ', '').replace('-', '')
-
-            # Navigate to chat using URL scheme
-            await page.goto(f'https://web.whatsapp.com/send?phone={phone}&text={message}')
-            await page.wait_for_load_state('networkidle')
-
-            # Wait for message input to be ready and the chat to load
-            try:
-                # Wait longer for chat to load
-                await page.wait_for_selector('div[contenteditable="true"], div[data-testid="popup-controls-ok"]', timeout=30000)
-            except Exception:
-                logger.warning("[WhatsApp Web] Timed out waiting for chat to load via URL")
-
-            # Check for invalid number popup
-            popup = page.locator('div[data-testid="popup-controls-ok"]')
-            if await popup.count() > 0:
-                await popup.click()
-                return {"success": False, "error": "Invalid phone number or chat not found via URL"}
-
-            # Wait a bit for text to populate from URL param
-            await asyncio.sleep(2)
-
-            # Try multiple selectors for the send button (WhatsApp Web changes these frequently)
-            send_selectors = [
-                '[data-testid="send"]',
-                '[data-icon="send"]',
-                'button[aria-label="Send"]',
-                'span[data-icon="send"]',
-                '[aria-label="Send"]',
-                'button:has(span[data-icon="send"])',
-                'div[role="button"][aria-label="Send"]'
-            ]
-
-            send_clicked = False
-            for selector in send_selectors:
-                try:
-                    send_btn = page.locator(selector)
-                    if await send_btn.count() > 0:
-                        await send_btn.first.click()
-                        send_clicked = True
-                        logger.info(f"[WhatsApp Web] Send button clicked with selector: {selector}")
-                        break
-                except Exception:
-                    continue
-
-            # Fallback: Press Enter key if no send button was clicked
-            if not send_clicked:
-                logger.info("[WhatsApp Web] Send button not found, using Enter key fallback")
-                # Find the message input and press Enter
-                input_selectors = [
-                    '[data-testid="conversation-compose-box-input"]',
-                    'div[contenteditable="true"][data-tab="10"]',
-                    'div[contenteditable="true"][role="textbox"]',
-                    'footer div[contenteditable="true"]',
-                    '#main footer div[contenteditable="true"]'
-                ]
-
-                for selector in input_selectors:
-                    try:
-                        input_box = page.locator(selector)
-                        if await input_box.count() > 0:
-                            # Ensure focused and press Enter
-                            await input_box.first.click()
-                            await input_box.first.press('Enter')
-                            send_clicked = True
-                            logger.info(f"[WhatsApp Web] Sent via Enter key on input: {selector}")
-                            break
-                    except Exception:
-                        continue
-
-            if send_clicked:
-                session.last_activity = datetime.utcnow()
-                # Wait a moment for message to be sent
-                await asyncio.sleep(2)
-                return {
-                    "success": True,
-                    "timestamp": datetime.utcnow().isoformat(),
-                }
-            
-            # If still failed, try manual fill and send (URL param might have failed)
-            logger.info("[WhatsApp Web] Trying manual fill fallback")
-            input_selectors = [
-                'div[contenteditable="true"][data-tab="10"]',
-                'div[contenteditable="true"][role="textbox"]',
-                'footer div[contenteditable="true"]'
-            ]
-            for selector in input_selectors:
-                try:
-                    input_box = page.locator(selector)
-                    if await input_box.count() > 0:
-                        await input_box.first.fill(message)
-                        await asyncio.sleep(0.5)
-                        await input_box.first.press('Enter')
-                        session.last_activity = datetime.utcnow()
-                        return {"success": True, "timestamp": datetime.utcnow().isoformat(), "note": "manual_fill"}
-                except Exception:
-                    continue
-
-            return {"success": False, "error": "Could not send message - no send button or input field found"}
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to send message: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def send_media(
-        self,
-        session_id: str,
-        to: str,
-        media_path: str,
-        caption: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """
-        Send media (image, video, document) via WhatsApp Web.
-
-        Args:
-            session_id: The session ID to use
-            to: Recipient phone number
-            media_path: Path to the media file
-            caption: Optional caption for the media
-
-        Returns:
-            Dict with message ID and status
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # Clean phone number
-            phone = to.lstrip('+').replace(' ', '').replace('-', '')
-
-            # Navigate to chat
-            await page.goto(f'https://web.whatsapp.com/send?phone={phone}')
-            await page.wait_for_load_state('networkidle')
-            await asyncio.sleep(3)
-
-            # Try multiple selectors for the attach button
-            attach_selectors = [
-                '[data-testid="attach-menu-plus"]',
-                '[data-icon="attach-menu-plus"]',
-                '[data-icon="plus"]',
-                '[data-testid="clip"]',
-                '[data-icon="clip"]',
-                'button[aria-label="Attach"]',
-                '[aria-label="Attach"]',
-                'span[data-icon="attach-menu-plus"]',
-                'span[data-icon="plus"]',
-            ]
-
-            attach_clicked = False
-            for selector in attach_selectors:
-                try:
-                    attach_btn = page.locator(selector)
-                    if await attach_btn.count() > 0:
-                        await attach_btn.first.click()
-                        attach_clicked = True
-                        logger.info(f"[WhatsApp Web] Attach button clicked with selector: {selector}")
-                        break
-                except Exception:
-                    continue
-
-            if not attach_clicked:
-                return {"success": False, "error": "Could not find attach button"}
-
-            await asyncio.sleep(1)
-
-            # Upload file
-            file_input = page.locator('input[type="file"]')
-            if await file_input.count() == 0:
-                return {"success": False, "error": "Could not find file input"}
-
-            await file_input.set_input_files(media_path)
-            await asyncio.sleep(3)
-
-            # Add caption if provided
-            if caption:
-                caption_selectors = [
-                    '[data-testid="media-caption-input-container"] [contenteditable="true"]',
-                    'div[data-testid="media-caption-text-input"]',
-                    '[aria-label="Add a caption"]',
-                    'div[contenteditable="true"][data-tab="6"]',
-                ]
-                for selector in caption_selectors:
-                    try:
-                        caption_input = page.locator(selector)
-                        if await caption_input.count() > 0:
-                            await caption_input.first.fill(caption)
-                            logger.info(f"[WhatsApp Web] Caption added with selector: {selector}")
-                            break
-                    except Exception:
-                        continue
-
-            # Try multiple selectors for the send button
-            send_selectors = [
-                '[data-testid="send"]',
-                '[data-icon="send"]',
-                'button[aria-label="Send"]',
-                'span[data-icon="send"]',
-                '[aria-label="Send"]',
-                'button:has(span[data-icon="send"])',
-            ]
-
-            send_clicked = False
-            for selector in send_selectors:
-                try:
-                    send_btn = page.locator(selector)
-                    if await send_btn.count() > 0:
-                        await send_btn.first.click()
-                        send_clicked = True
-                        logger.info(f"[WhatsApp Web] Media send button clicked with selector: {selector}")
-                        break
-                except Exception:
-                    continue
-
-            if send_clicked:
-                session.last_activity = datetime.utcnow()
-                await asyncio.sleep(1)
-                return {
-                    "success": True,
-                    "timestamp": datetime.utcnow().isoformat(),
-                }
-
-            return {"success": False, "error": "Could not find send button after attaching media"}
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to send media: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def get_chat_messages(
-        self,
-        session_id: str,
-        phone_number: str,
-        limit: int = 50,
-    ) -> Dict[str, Any]:
-        """
-        Get recent messages from a specific chat.
-
-        Args:
-            session_id: The session ID
-            phone_number: The phone number to get messages from
-            limit: Maximum number of messages to retrieve (default 50)
-
-        Returns:
-            Dict with success status and list of messages
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # Clean phone number
-            phone = phone_number.lstrip('+').replace(' ', '').replace('-', '')
-
-            # Navigate to chat
-            await page.goto(f'https://web.whatsapp.com/send?phone={phone}')
-            await page.wait_for_load_state('networkidle')
-            await asyncio.sleep(5)  # Wait for chat history to load
-
-            # Check for invalid number popup
-            popup = page.locator('div[data-testid="popup-controls-ok"]')
-            if await popup.count() > 0:
-                await popup.click()
-                return {"success": False, "error": "Invalid phone number"}
-
-            # Get messages
-            # Select all message rows
-            message_rows = page.locator('div[role="row"]')
-            
-            # Wait for at least one message or timeout (new chat might be empty)
-            try:
-                await message_rows.first.wait_for(timeout=5000)
-            except:
-                pass # Might be empty chat
-
-            count = await message_rows.count()
-            logger.info(f"[WhatsApp Web] Found {count} messages in chat")
-
-            messages = []
-            # Calculate start index to get only the last 'limit' messages
-            start_idx = max(0, count - limit)
-            
-            for i in range(start_idx, count):
-                try:
-                    row = message_rows.nth(i)
-                    
-                    # Determine if incoming or outgoing
-                    is_outgoing = await row.locator('.message-out').count() > 0
-                    
-                    # 1. Try to get text from span.selectable-text (most common for text msgs)
-                    text_elems = row.locator('span.selectable-text')
-                    text = ""
-                    if await text_elems.count() > 0:
-                        # Collect all text parts
-                        text_parts = []
-                        for j in range(await text_elems.count()):
-                             # Filter out empty spans
-                             t = await text_elems.nth(j).inner_text()
-                             if t.strip():
-                                 text_parts.append(t)
-                        text = "\n".join(text_parts)
-                    
-                    # 2. If no text, check for specific media indicators
-                    if not text:
-                        # Check for video
-                        if await row.locator('video').count() > 0:
-                            text = "[Video]"
-                        # Check for image (exclude profile pics/emojis which are small)
-                        # We look for img tags that are likely content
-                        elif await row.locator('img[src*="blob:"]').count() > 0:
-                             text = "[Image]"
-                        
-                        # Only label as generic media if we really can't find text and it seems to contain visual elements
-                        elif await row.locator('div[data-testid="media-msg"]').count() > 0:
-                             text = "[Media]"
-
-                    # 3. Timestamp/Sender from metadata
-                    timestamp = ""
-                    sender = "them"
-                    if is_outgoing:
-                        sender = "me"
-                    
-                    # The container with class 'copyable-text' has data-pre-plain-text
-                    copyable = row.locator('div.copyable-text').first
-                    if await copyable.count() > 0:
-                        data_pre = await copyable.get_attribute('data-pre-plain-text')
-                        if data_pre:
-                            # Clean up the format: "[10:30, 02/02/2026] Name: "
-                            timestamp = data_pre.split(']')[0].replace('[', '').strip()
-                            if not is_outgoing:
-                                parts = data_pre.split(']')
-                                if len(parts) > 1:
-                                    sender = parts[1].strip().rstrip(':')
-
-                    # Final check: if text is empty and it's not explicitly media, try to grab *any* text as fallback
-                    # This catches system messages or weirdly formatted text
-                    if not text and not text.startswith("["):
-                        try:
-                            # Try getting all text from the row, excluding time
-                            all_text = await row.inner_text()
-                            lines = all_text.split('\n')
-                            if lines:
-                                # First line is often the content if it's not empty
-                                candidate = lines[0].strip()
-                                if candidate and candidate != timestamp and candidate != sender:
-                                    text = candidate
-                        except Exception:
-                            pass
-
-                    messages.append({
-                        "text": text,
-                        "is_outgoing": is_outgoing,
-                        "timestamp": timestamp,
-                        "sender": sender
-                    })
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Error parsing message row {i}: {e}")
-                    continue
-
-            return {
-                "success": True, 
-                "messages": messages,
-                "count": len(messages),
-                "chat": phone_number
-            }
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to get messages: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def get_chat_messages_by_name(
-        self,
-        session_id: str,
-        chat_name: str,
-        limit: int = 50,
-    ) -> Dict[str, Any]:
-        """
-        Open a chat by clicking on it in the sidebar and read its messages.
-
-        Unlike get_chat_messages (which navigates via phone URL), this method
-        clicks the chat entry in the sidebar by name.  This is suitable for
-        the polling loop where we already know the chat name from
-        get_unread_chats.
-
-        Returns:
-            Dict with success status and list of messages
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # Find the chat in the sidebar by its title/name
-            chat_item = page.locator(f'span[title="{chat_name}"]').first
-            if await chat_item.count() == 0:
-                # Try a more relaxed match (contains)
-                chat_item = page.locator(f'span[title*="{chat_name}"]').first
-                if await chat_item.count() == 0:
-                    return {"success": False, "error": f"Chat '{chat_name}' not found in sidebar"}
-
-            # Click on the chat to open it
-            await chat_item.click()
-            await asyncio.sleep(2)  # Wait for chat to load
-
-            # Read messages from the open chat (reuse the same scraping logic)
-            message_rows = page.locator('div[role="row"]')
-            try:
-                await message_rows.first.wait_for(timeout=5000)
-            except Exception:
-                pass  # Might be empty chat
-
-            count = await message_rows.count()
-            messages = []
-            start_idx = max(0, count - limit)
-
-            for i in range(start_idx, count):
-                try:
-                    row = message_rows.nth(i)
-
-                    is_outgoing = await row.locator('.message-out').count() > 0
-
-                    text_elems = row.locator('span.selectable-text')
-                    text = ""
-                    if await text_elems.count() > 0:
-                        text_parts = []
-                        for j in range(await text_elems.count()):
-                            t = await text_elems.nth(j).inner_text()
-                            if t.strip():
-                                text_parts.append(t)
-                        text = "\n".join(text_parts)
-
-                    if not text:
-                        if await row.locator('video').count() > 0:
-                            text = "[Video]"
-                        elif await row.locator('img[src*="blob:"]').count() > 0:
-                            text = "[Image]"
-                        elif await row.locator('div[data-testid="media-msg"]').count() > 0:
-                            text = "[Media]"
-
-                    timestamp = ""
-                    sender = "them"
-                    if is_outgoing:
-                        sender = "me"
-
-                    copyable = row.locator('div.copyable-text').first
-                    if await copyable.count() > 0:
-                        data_pre = await copyable.get_attribute('data-pre-plain-text')
-                        if data_pre:
-                            timestamp = data_pre.split(']')[0].replace('[', '').strip()
-                            if not is_outgoing:
-                                parts = data_pre.split(']')
-                                if len(parts) > 1:
-                                    sender = parts[1].strip().rstrip(':')
-
-                    if not text and not text.startswith("["):
-                        try:
-                            all_text = await row.inner_text()
-                            lines = all_text.split('\n')
-                            if lines:
-                                candidate = lines[0].strip()
-                                if candidate and candidate != timestamp and candidate != sender:
-                                    text = candidate
-                        except Exception:
-                            pass
-
-                    messages.append({
-                        "text": text,
-                        "is_outgoing": is_outgoing,
-                        "timestamp": timestamp,
-                        "sender": sender,
-                    })
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Error parsing message row {i}: {e}")
-                    continue
-
-            return {
-                "success": True,
-                "messages": messages,
-                "count": len(messages),
-                "chat": chat_name,
-            }
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to get messages by name for '{chat_name}': {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def get_own_profile_name(
-        self,
-        session_id: str,
-    ) -> Optional[str]:
-        """Return the logged-in user's own WhatsApp display name, or *None*."""
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-        if not page or not session or session.status != "connected":
-            return None
-        try:
-            name = await page.evaluate("""() => {
-                // The profile avatar button at the top-left of the sidebar
-                // contains a clickable img whose alt text is the user's name.
-                const avatar = document.querySelector(
-                    'header img[alt]'
-                );
-                if (avatar) {
-                    const alt = avatar.getAttribute('alt');
-                    if (alt && alt.length > 0) return alt;
-                }
-                // Fallback: the header span with the user's name
-                const headerSpan = document.querySelector(
-                    'header span[title]'
-                );
-                if (headerSpan) return headerSpan.getAttribute('title') || '';
-                return '';
-            }""")
-            return name if name else None
-        except Exception as e:
-            logger.debug(f"[WhatsApp Web] Could not read own profile name: {e}")
-            return None
-
-    async def get_unread_chats(
-        self,
-        session_id: str,
-    ) -> Dict[str, Any]:
-        """
-        Get a list of chats that have unread messages.
-        
-        Returns:
-            Dict with list of unread chats (names/numbers and unread counts)
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # Use JavaScript to extract chat data from the sidebar.
-            # We collect: name, badge count, and a stable preview fingerprint
-            # built from ALL text inside the row (minus the name and timestamp).
-            chat_data = await page.evaluate("""() => {
-                const rows = document.querySelectorAll('#pane-side div[role="row"]');
-                const seen = new Set();
-                const results = [];
-                for (const row of rows) {
-                    // 1. Chat name: first span[title] in the row
-                    const nameEl = row.querySelector('span[title]');
-                    if (!nameEl) continue;
-                    const name = nameEl.getAttribute('title') || nameEl.textContent || '';
-                    if (!name || seen.has(name)) continue;
-                    seen.add(name);
-
-                    // 2. Unread badge: find a small span with only digits
-                    //    and a colored background (the green unread circle)
-                    let unreadCount = 0;
-                    const allSpans = row.querySelectorAll('span');
-                    for (const sp of allSpans) {
-                        const txt = sp.textContent.trim();
-                        if (/^\\d{1,4}$/.test(txt) && sp !== nameEl) {
-                            const rect = sp.getBoundingClientRect();
-                            if (rect.width > 0 && rect.width < 40 && rect.height < 30) {
-                                const el = sp.closest('[style]') || sp.parentElement;
-                                const style = window.getComputedStyle(el || sp);
-                                const bg = style.backgroundColor;
-                                if (bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent') {
-                                    unreadCount = parseInt(txt, 10);
-                                    break;
-                                }
-                            }
-                        }
-                    }
-
-                    // 3. Muted: broad search for any mute-related icon/element
-                    let isMuted = false;
-                    const allIcons = row.querySelectorAll('span[data-icon]');
-                    for (const ic of allIcons) {
-                        const iconName = ic.getAttribute('data-icon') || '';
-                        if (iconName.toLowerCase().includes('mute')) {
-                            isMuted = true;
-                            break;
-                        }
-                    }
-                    if (!isMuted) {
-                        const allTestIds = row.querySelectorAll('[data-testid]');
-                        for (const el of allTestIds) {
-                            const tid = el.getAttribute('data-testid') || '';
-                            if (tid.toLowerCase().includes('mute')) {
-                                isMuted = true;
-                                break;
-                            }
-                        }
-                    }
-
-                    // 4. Group detection (best-effort from sidebar)
-                    let isGroup = false;
-                    // a) default-group icon
-                    const groupIcons = row.querySelectorAll('span[data-icon]');
-                    for (const ic of groupIcons) {
-                        const iconName = ic.getAttribute('data-icon') || '';
-                        if (iconName.includes('group')) {
-                            isGroup = true;
-                            break;
-                        }
-                    }
-                    if (!isGroup) {
-                        const fullInner = row.innerText || '';
-                        // b) System messages that indicate groups
-                        const lowerInner = fullInner.toLowerCase();
-                        if (lowerInner.includes('group members')
-                            || lowerInner.includes('added you')
-                            || lowerInner.includes('created group')
-                            || lowerInner.includes('changed the subject')) {
-                            isGroup = true;
-                        }
-                        // c) "Sender: msg" pattern in preview
-                        if (!isGroup) {
-                            const nbsp = String.fromCharCode(160);
-                            const collapsed = fullInner.replace(/\\n:\\s*/g, ': ').replace(/:\\s*\\n/g, ': ').replaceAll(':' + nbsp, ': ');
-                            const lines = collapsed.split('\\n').map(l => l.trim()).filter(Boolean);
-                            for (let k = 1; k < lines.length; k++) {
-                                const line = lines[k];
-                                if (/^[^:]{1,30}:\\s/.test(line)
-                                    && !/^\\d{1,2}:\\d{2}/.test(line)
-                                    && !line.startsWith('http')) {
-                                    isGroup = true;
-                                    break;
-                                }
-                            }
-                        }
-                    }
-
-                    // 5. Stable preview
-                    const fullText = row.innerText.trim();
-
-                    // 6. Debug: collect data-icon names in this row
-                    const icons = [];
-                    for (const ic of row.querySelectorAll('span[data-icon]')) {
-                        icons.push(ic.getAttribute('data-icon'));
-                    }
-
-                    results.push({
-                        name: name,
-                        unread_count: unreadCount,
-                        is_muted: isMuted,
-                        is_group: isGroup,
-                        full_text: fullText.substring(0, 300),
-                        _icons: icons,
-                    });
-                }
-                return results;
-            }""")
-
-            if not chat_data:
-                return {"success": True, "unread_chats": [], "count": 0}
-
-            # Log sample once for debugging
-            if not hasattr(self, '_first_poll_logged'):
-                self._first_poll_logged = True
-                sample = chat_data[:5]
-                logger.info(f"[WhatsApp Web] Sample chat rows ({len(chat_data)} total): {sample}")
-
-            unread_chats = []
-
-            for chat in chat_data:
-                name = chat.get("name", "")
-                badge_count = chat.get("unread_count", 0)
-                full_text = chat.get("full_text", "")
-                is_muted = chat.get("is_muted", False)
-                is_group = chat.get("is_group", False)
-
-                if not name:
-                    continue
-
-                # Build a stable fingerprint from the preview: keep only the
-                # last message line and strip all volatile metadata (timestamps,
-                # dates, delivery indicators, etc.) that WhatsApp re-renders.
-                lines = [l.strip() for l in full_text.split('\n') if l.strip()]
-                # Last meaningful line is typically the message content.
-                # Drop lines that are just the chat name, dates, timestamps,
-                # "(You)", or badge counts.
-                msg_lines = []
-                for line in lines:
-                    # Skip: chat name itself, timestamps, date words, "(You)", pure numbers (badge counts)
-                    if line == name:
-                        continue
-                    if re.match(r'^\d{1,2}:\d{2}$', line):
-                        continue
-                    if re.match(r'^\d{1,2}/\d{1,2}/\d{2,4}$', line):
-                        continue
-                    if line.lower() in ('yesterday', 'today', '(you)'):
-                        continue
-                    if re.match(r'^\d{1,3}$', line):
-                        continue
-                    msg_lines.append(line)
-                stable_text = '\n'.join(msg_lines)
-
-                # Method 1: Has an unread badge (works for others' messages)
-                if badge_count > 0:
-                    unread_chats.append({
-                        "name": name,
-                        "unread_count": str(badge_count),
-                        "source": "badge",
-                        "is_muted": is_muted,
-                        "is_group": is_group,
-                    })
-                    self._chat_previews[name] = stable_text
-                    continue
-
-                # Method 2: Message content changed (catches self-messages
-                # and any case without badges)
-                old_text = self._chat_previews.get(name)
-                if old_text is not None and stable_text and stable_text != old_text:
-                    logger.info(f"[WhatsApp Web] Chat changed: '{name}'")
-                    unread_chats.append({
-                        "name": name,
-                        "unread_count": "1",
-                        "source": "preview_change",
-                        "is_muted": is_muted,
-                        "is_group": is_group,
-                    })
-
-                if stable_text:
-                    self._chat_previews[name] = stable_text
-
-            if unread_chats:
-                logger.info(f"[WhatsApp Web] Chats with activity: {[(c['name'], c['unread_count']) for c in unread_chats]}")
-
-            return {
-                "success": True,
-                "unread_chats": unread_chats,
-                "count": len(unread_chats)
-            }
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to get unread chats: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def resolve_contact_phone(
-        self,
-        session_id: str,
-        name: str,
-    ) -> Dict[str, Any]:
-        """
-        Resolve a contact name to a phone number using fuzzy matching.
-
-        This function searches for contacts and uses fuzzy matching to find the best match.
-        For example, "Emad Tavana" will match "Emad Tavana MDX" but NOT "Emad Davane".
-        """
-        page = self._pages.get(session_id)
-        session = self._sessions.get(session_id)
-
-        if not page or not session or session.status != "connected":
-            return {"success": False, "error": "Session not connected"}
-
-        try:
-            # Clear any previous search
-            # Try multiple selectors for search bar
-            search_selectors = [
-                'div[contenteditable="true"][data-tab="3"]',
-                '[data-testid="chat-list-search"]',
-                '[aria-label="Search or start new chat"]',
-                '[title="Search input textbox"]'
-            ]
-
-            search_box = None
-            for selector in search_selectors:
-                if await page.locator(selector).count() > 0:
-                    search_box = page.locator(selector).first
-                    break
-
-            if not search_box:
-                return {"success": False, "error": "Could not find search bar"}
-
-            await search_box.click()
-            await search_box.fill("")
-            await asyncio.sleep(0.5)
-
-            logger.info(f"[WhatsApp Web] Searching for contact: '{name}'")
-            await search_box.fill(name)
-
-            # Wait for results
-            await asyncio.sleep(2)
-
-            # Use span[title] elements directly since they reliably contain contact names
-            # The container selectors change frequently, but span[title] is stable
-            all_titles = page.locator('#pane-side span[title]')
-            title_count = await all_titles.count()
-
-            logger.info(f"[WhatsApp Web] Found {title_count} span[title] elements in side pane")
-
-            if title_count == 0:
-                await asyncio.sleep(2)
-                title_count = await all_titles.count()
-                logger.info(f"[WhatsApp Web] After retry: {title_count} span[title] elements")
-
-            if title_count == 0:
-                return {"success": False, "error": f"No contacts visible on page for '{name}'"}
-
-            # Collect all visible contact names and find the best fuzzy match
-            best_match_elem = None
-            best_match_score = 0.0
-            best_match_name = ""
-            candidates = []
-            seen_names = set()  # Avoid duplicates
-
-            for i in range(min(title_count, 30)):  # Check up to 30 results
-                try:
-                    title_elem = all_titles.nth(i)
-                    contact_name = await title_elem.get_attribute('title')
-
-                    if not contact_name or len(contact_name) < 2:
-                        continue
-
-                    # Skip duplicates and system messages
-                    if contact_name in seen_names:
-                        continue
-                    seen_names.add(contact_name)
-
-                    # Skip obvious non-contact entries (system messages, etc.)
-                    if contact_name.startswith('\u202a') or 'also in this group' in contact_name.lower():
-                        continue
-
-                    is_match, score = _fuzzy_name_match(name, contact_name)
-                    candidates.append({"name": contact_name, "score": score, "is_match": is_match, "elem": title_elem})
-                    logger.debug(f"[WhatsApp Web] Contact candidate: '{contact_name}' - score: {score:.2f}, match: {is_match}")
-
-                    if is_match and score > best_match_score:
-                        best_match_score = score
-                        best_match_elem = title_elem
-                        best_match_name = contact_name
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Error checking title {i}: {e}")
-                    continue
-
-            if best_match_elem is None:
-                # No good fuzzy match found
-                candidate_names = [c["name"] for c in candidates[:5] if c.get("name")]
-                logger.info(f"[WhatsApp Web] No fuzzy match for '{name}'. Candidates: {candidate_names}")
-                return {
-                    "success": False,
-                    "error": f"No contact found matching '{name}'. Similar contacts: {', '.join(candidate_names) if candidate_names else 'none'}"
-                }
-
-            logger.info(f"[WhatsApp Web] Best fuzzy match for '{name}': '{best_match_name}' (score: {best_match_score:.2f})")
-
-            # Click the best matching result (click the span element itself)
-            await best_match_elem.click()
-
-            # Wait for chat to load
-            await asyncio.sleep(2)
-
-            # Click header to open info - the clickable area in WhatsApp Web is usually a div containing the contact info
-            # We need to find the right clickable area that opens the contact drawer
-
-            # First, let's try clicking the header section that contains contact info
-            # WhatsApp Web typically has a clickable section with the contact name and status
-            header_click_attempts = [
-                # Try clicking the conversation panel header (the whole clickable area)
-                ('#main header [data-testid="conversation-panel-header"]', 'conversation-panel-header'),
-                # Try the section containing avatar and name
-                ('#main header section', 'header section'),
-                # Try clicking the div containing the title
-                ('#main header div[title]', 'header div with title'),
-                # The contact name span's parent (usually a clickable div)
-                ('#main header span[title]', 'span title (then parent)'),
-                # Avatar in header
-                ('#main header [data-testid="avatar"]', 'avatar'),
-                ('#main header img[draggable="false"]', 'avatar img'),
-                # The whole header as last resort
-                ('#main header', 'whole header'),
-            ]
-
-            clicked = False
-            for sel, desc in header_click_attempts:
-                try:
-                    elem = page.locator(sel).first
-                    if await elem.count() > 0:
-                        logger.debug(f"[WhatsApp Web] Trying to click: {desc} ({sel})")
-
-                        # For span[title], try clicking its parent instead
-                        if 'span[title]' in sel:
-                            # Get bounding box and click in the center area of the header
-                            box = await elem.bounding_box()
-                            if box:
-                                # Click slightly to the left of the span (in the avatar/name area)
-                                await page.mouse.click(box['x'] - 50, box['y'] + box['height'] / 2)
-                                logger.debug(f"[WhatsApp Web] Clicked near span title at x={box['x']-50}")
-                                clicked = True
-                                break
-                        else:
-                            await elem.click(force=True)
-                            clicked = True
-                            logger.debug(f"[WhatsApp Web] Clicked: {desc}")
-                            break
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Failed to click {desc}: {e}")
-                    continue
-
-            if not clicked:
-                logger.warning("[WhatsApp Web] Could not find/click chat header")
-                return {"success": False, "error": "Could not find chat header"}
-
-            # Wait for panel to open
-            await asyncio.sleep(3)
-
-            # Check if any new panel appeared by looking for common drawer elements
-            logger.debug("[WhatsApp Web] Checking for opened panel...")
-
-            # Look for phone in sidebar (right side) - try multiple selectors
-            side_panel_selectors = [
-                'div[data-testid="contact-info-drawer"]',
-                'div[data-testid="group-info-drawer"]',
-                'div[data-testid="chat-info-drawer"]',
-                '[data-testid="contact-info-drawer"]',
-                '#app div[tabindex="-1"][data-animate-modal-popup="true"]',
-                'section[data-testid="contact-info"]',
-                # Try any drawer/panel that appeared
-                'div[data-animate-drawer="true"]',
-                'div[style*="transform: translateX(0"]',  # Visible drawer
-                '#app > div > div > div:nth-child(3)',  # Third column (right panel)
-            ]
-
-            side_panel = None
-            for sel in side_panel_selectors:
-                try:
-                    loc = page.locator(sel)
-                    cnt = await loc.count()
-                    if cnt > 0:
-                        side_panel = loc.first
-                        logger.debug(f"[WhatsApp Web] Found side panel with selector: {sel} (count: {cnt})")
-                        break
-                except Exception:
-                    continue
-
-            # Debug: Log all divs with data-testid to see what's available
-            if not side_panel:
-                try:
-                    testids = page.locator('[data-testid]')
-                    testid_count = await testids.count()
-                    testid_names = []
-                    for i in range(min(testid_count, 30)):
-                        try:
-                            tid = await testids.nth(i).get_attribute('data-testid')
-                            if tid and 'drawer' in tid.lower() or 'info' in tid.lower() or 'panel' in tid.lower():
-                                testid_names.append(tid)
-                        except Exception:
-                            pass
-                    if testid_names:
-                        logger.debug(f"[WhatsApp Web] Available data-testid with drawer/info/panel: {testid_names}")
-                except Exception:
-                    pass
-
-            phone = None
-            panel_text = ""
-
-            # If we found a side panel with specific selectors, use it
-            if side_panel:
-                try:
-                    panel_text = await side_panel.inner_text()
-                    logger.debug(f"[WhatsApp Web] Side panel text (first 300 chars): {panel_text[:300]}")
-                except Exception as e:
-                    logger.warning(f"[WhatsApp Web] Error getting side panel text: {e}")
-
-            # If no specific panel found, try to find the contact info section
-            # by looking for the panel that opened (contains "Close" button)
-            if not panel_text or panel_text == "Close":
-                logger.debug("[WhatsApp Web] Trying alternative panel detection...")
-                try:
-                    # Find the close button and get content from its sibling/parent
-                    close_btn = page.locator('[aria-label="Close"], [data-testid="x"], [data-icon="x"]').first
-                    if await close_btn.count() > 0:
-                        # Get the parent container of the close button (usually the drawer)
-                        # Try to get all text from the page's right section
-                        # WhatsApp structure: #app > div > div > div (left) + div (center/main) + div (right panel)
-                        all_divs = page.locator('#app > div > div > div')
-                        div_count = await all_divs.count()
-                        logger.debug(f"[WhatsApp Web] Found {div_count} main divs in app")
-
-                        # The rightmost div (if 3 exist) should be the info panel
-                        if div_count >= 3:
-                            right_panel = all_divs.nth(2)  # 0-indexed, so 2 is the third
-                            panel_text = await right_panel.inner_text()
-                            logger.debug(f"[WhatsApp Web] Right panel (div 2) text (first 500 chars): {panel_text[:500]}")
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Alternative panel detection failed: {e}")
-
-            # Now search for phone number in the panel text
-            if panel_text and len(panel_text) > 10:
-                # Pattern 1: International format +1 234 567 8900 or +44 7xxx
-                phones = re.findall(r'\+\d[\d\s-]{7,}', panel_text)
-                if phones:
-                    phone = phones[0].strip().replace(" ", "").replace("-", "")
-                    logger.debug(f"[WhatsApp Web] Found phone (pattern 1): {phone}")
-
-                # Pattern 2: Phone with country code but no + (like "44 7911 123456")
-                if not phone:
-                    # Look for sequences that look like phone numbers
-                    phone_candidates = re.findall(r'(?<!\d)(\d{10,15})(?!\d)', panel_text.replace(" ", "").replace("-", ""))
-                    if phone_candidates:
-                        phone = "+" + phone_candidates[0]
-                        logger.debug(f"[WhatsApp Web] Found phone (pattern 2): {phone}")
-
-            # If still no phone from text, try span elements directly on the page
-            if not phone:
-                try:
-                    # Look for any span on page with phone number in title or text
-                    phone_spans = page.locator('span[title*="+"]')
-                    span_count = await phone_spans.count()
-                    logger.debug(f"[WhatsApp Web] Found {span_count} spans with + in title")
-                    for i in range(min(span_count, 20)):
-                        try:
-                            title = await phone_spans.nth(i).get_attribute('title')
-                            if title and re.match(r'^\+\d[\d\s-]{7,}$', title.strip()):
-                                phone = title.strip().replace(" ", "").replace("-", "")
-                                logger.debug(f"[WhatsApp Web] Found phone from span title: {phone}")
-                                break
-                        except Exception:
-                            continue
-                except Exception as e:
-                    logger.debug(f"[WhatsApp Web] Span search failed: {e}")
-
-            # Close info drawer
-            close_btn = page.locator('[data-testid="x"], [data-icon="x"], [aria-label="Close"]')
-            if await close_btn.count() > 0:
-                try:
-                    await close_btn.first.click()
-                except Exception:
-                    pass
-
-            if phone:
-                return {"success": True, "name": best_match_name, "phone": phone}
-            else:
-                # Fallback: if user provided a name that IS the phone number
-                if name.replace("+", "").replace(" ", "").isdigit():
-                    return {"success": True, "name": name, "phone": name}
-
-                return {
-                    "success": False,
-                    "error": f"Contact '{best_match_name}' found but could not extract phone number from profile",
-                    "debug": {
-                        "panel_text_preview": panel_text[:200] if panel_text else "no panel text"
-                    }
-                }
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to resolve contact: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-    async def export_session_data(self, session_id: str) -> Optional[Dict[str, Any]]:
-        """
-        Export session data (cookies, localStorage) for a connected session.
-
-        This allows the session to be transferred to another agent.
-        Note: WhatsApp Web stores session keys in IndexedDB which may not be
-        fully captured - the receiving agent may need to re-authenticate.
-
-        Returns:
-            Dict with storage_state (cookies, localStorage) or None if session not found
-        """
-        if session_id not in self._browsers:
-            logger.warning(f"[WhatsApp Web] Cannot export session {session_id}: no active browser")
-            return None
-
-        session = self._sessions.get(session_id)
-        if not session or session.status != "connected":
-            logger.warning(f"[WhatsApp Web] Cannot export session {session_id}: not connected")
-            return None
-
-        try:
-            playwright, browser = self._browsers[session_id]
-            # Export storage state (cookies and localStorage)
-            storage_state = await browser.storage_state()
-
-            logger.info(f"[WhatsApp Web] Exported session data for {session_id}")
-            return {
-                "storage_state": storage_state,
-                "jid": session.jid,
-                "phone_number": session.phone_number,
-            }
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to export session data for {session_id}: {e}")
-            return None
-
-    async def restore_session_from_data(
-        self,
-        session_id: str,
-        user_id: str,
-        session_data: Dict[str, Any],
-        on_connected: Optional[Callable[[str, str], None]] = None,
-        on_disconnected: Optional[Callable[[], None]] = None,
-    ) -> Dict[str, Any]:
-        """
-        Restore a WhatsApp Web session from exported session data.
-
-        This is used when receiving credentials from another agent.
-
-        Args:
-            session_id: Session identifier
-            user_id: User ID to associate
-            session_data: Exported session data containing storage_state
-            on_connected: Callback when connected
-            on_disconnected: Callback when disconnected
-
-        Returns:
-            Dict with status and session info
-        """
-        if session_id in self._sessions:
-            session = self._sessions[session_id]
-            return {
-                "success": True,
-                "status": session.status,
-                "session_id": session_id,
-                "message": "Session already active"
-            }
-
-        storage_state = session_data.get("storage_state")
-        if not storage_state:
-            return {
-                "success": False,
-                "error": "No storage_state in session_data"
-            }
-
-        try:
-            from playwright.async_api import async_playwright
-
-            logger.info(f"[WhatsApp Web] Restoring session {session_id} from session data")
-
-            # Create session object
-            session = WhatsAppWebSession(
-                session_id=session_id,
-                user_id=user_id,
-                status="restoring",
-                jid=session_data.get("jid"),
-                phone_number=session_data.get("phone_number"),
-                created_at=datetime.utcnow(),
-            )
-            self._sessions[session_id] = session
-
-            # Get or create session directory for persistent context
-            session_path = self._get_session_path(session_id)
-            session_path.mkdir(parents=True, exist_ok=True)
-
-            # Launch browser with persistent context
-            playwright = await async_playwright().start()
-            self._playwright_loop = asyncio.get_running_loop()
-            browser = await playwright.chromium.launch_persistent_context(
-                user_data_dir=str(session_path),
-                headless=True,
-                storage_state=storage_state,  # Inject the storage state
-                args=[
-                    '--no-sandbox',
-                    '--disable-setuid-sandbox',
-                    '--disable-dev-shm-usage',
-                    '--disable-accelerated-2d-canvas',
-                    '--no-first-run',
-                    '--no-zygote',
-                    '--disable-gpu',
-                    '--disable-blink-features=AutomationControlled',
-                ],
-                user_agent='Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
-                viewport={'width': 1280, 'height': 800},
-                locale='en-US',
-            )
-
-            self._browsers[session_id] = (playwright, browser)
-
-            # Get page
-            pages = browser.pages
-            if pages:
-                page = pages[0]
-            else:
-                page = await browser.new_page()
-            self._pages[session_id] = page
-
-            # Navigate to WhatsApp Web
-            logger.info(f"[WhatsApp Web] Navigating to WhatsApp Web for restored session...")
-            await page.goto('https://web.whatsapp.com', wait_until='domcontentloaded', timeout=60000)
-            await page.wait_for_load_state('networkidle', timeout=30000)
-
-            # Wait for page to stabilize
-            await asyncio.sleep(3)
-
-            # Check if logged in
-            logged_in_selectors = [
-                '[data-testid="chat-list"]',
-                'div[data-tab="3"]',
-                '#side',
-            ]
-
-            is_logged_in = False
-            for selector in logged_in_selectors:
-                try:
-                    if await page.locator(selector).count() > 0:
-                        is_logged_in = True
-                        break
-                except Exception:
-                    continue
-
-            if is_logged_in:
-                session.status = "connected"
-                session.last_activity = datetime.utcnow()
-                logger.info(f"[WhatsApp Web] Session {session_id} restored successfully!")
-
-                if on_connected:
-                    on_connected(session.jid or "", session.phone_number or "")
-
-                return {
-                    "success": True,
-                    "status": "connected",
-                    "session_id": session_id,
-                    "jid": session.jid,
-                    "phone_number": session.phone_number,
-                    "message": "Successfully restored WhatsApp Web session"
-                }
-            else:
-                # Check if QR code is shown
-                qr_selectors = [
-                    'canvas[aria-label="Scan this QR code to link a device!"]',
-                    'canvas[aria-label*="QR"]',
-                    '[data-testid="qrcode"]',
-                ]
-
-                needs_qr = False
-                for selector in qr_selectors:
-                    try:
-                        if await page.locator(selector).count() > 0:
-                            needs_qr = True
-                            break
-                    except Exception:
-                        continue
-
-                if needs_qr:
-                    session.status = "qr_required"
-                    logger.warning(f"[WhatsApp Web] Restored session {session_id} requires new QR scan")
-                    return {
-                        "success": False,
-                        "status": "qr_required",
-                        "session_id": session_id,
-                        "error": "Session data was transferred but WhatsApp requires re-authentication.",
-                        "hint": "The session may have expired. Start a new session and scan the QR code."
-                    }
-                else:
-                    session.status = "unknown"
-                    return {
-                        "success": False,
-                        "status": "unknown",
-                        "session_id": session_id,
-                        "error": "Could not determine session state after restore."
-                    }
-
-        except ImportError as e:
-            logger.error(f"[WhatsApp Web] Playwright not installed: {e}")
-            return {"success": False, "error": "Playwright not installed"}
-
-        except Exception as e:
-            logger.error(f"[WhatsApp Web] Failed to restore session: {e}", exc_info=True)
-            return {"success": False, "error": str(e)}
-
-
-# Global manager instance
-_manager: Optional[WhatsAppWebManager] = None
-
-
-def get_whatsapp_web_manager() -> WhatsAppWebManager:
-    """Get the global WhatsApp Web manager instance."""
-    global _manager
-    if _manager is None:
-        _manager = WhatsAppWebManager()
-    return _manager
-
-
-# Convenience functions for direct use
-
-async def start_whatsapp_web_session(
-    user_id: str,
-    session_id: Optional[str] = None,
-) -> WhatsAppWebSession:
-    """Start a new WhatsApp Web session and get QR code."""
-    manager = get_whatsapp_web_manager()
-    return await manager.create_session(user_id, session_id)
-
-
-async def get_session_status(session_id: str, include_session_data: bool = False) -> Optional[Dict[str, Any]]:
-    """
-    Get the current status of a WhatsApp Web session.
-
-    Args:
-        session_id: The session ID to check
-        include_session_data: If True and session is connected, include exportable session data
-    """
-    manager = get_whatsapp_web_manager()
-    session = manager.get_session(session_id)
-    if not session:
-        return None
-
-    result = {
-        "session_id": session.session_id,
-        "user_id": session.user_id,
-        "status": session.status,
-        "qr_code": session.qr_code,
-        "phone_number": session.phone_number,
-        "jid": session.jid,
-        "created_at": session.created_at.isoformat() if session.created_at else None,
-    }
-
-    # Include session data for backend storage when connected
-    if include_session_data and session.status == "connected":
-        session_data = await manager.export_session_data(session_id)
-        if session_data:
-            result["session_data"] = session_data
-
-    return result
-
-
-async def export_whatsapp_web_session_data(session_id: str) -> Optional[Dict[str, Any]]:
-    """Export session data for a connected WhatsApp Web session."""
-    manager = get_whatsapp_web_manager()
-    return await manager.export_session_data(session_id)
-
-
-async def restore_whatsapp_web_session(
-    session_id: str,
-    user_id: str,
-    session_data: Dict[str, Any],
-) -> Dict[str, Any]:
-    """
-    Restore a WhatsApp Web session from exported session data.
-
-    This is used when receiving credentials from another agent.
-    """
-    manager = get_whatsapp_web_manager()
-    return await manager.restore_session_from_data(session_id, user_id, session_data)
-
-
-async def send_whatsapp_web_message(
-    session_id: str,
-    to: str,
-    message: str,
-) -> Dict[str, Any]:
-    """Send a message via WhatsApp Web."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.send_message(session_id, to, message)
-    )
-
-
-async def disconnect_whatsapp_web_session(session_id: str) -> bool:
-    """Disconnect a WhatsApp Web session."""
-    manager = get_whatsapp_web_manager()
-    return await manager.disconnect_session(session_id)
-
-
-async def send_whatsapp_web_media(
-    session_id: str,
-    to: str,
-    media_path: str,
-    caption: Optional[str] = None,
-) -> Dict[str, Any]:
-    """Send media via WhatsApp Web."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.send_media(session_id, to, media_path, caption)
-    )
-
-
-async def reconnect_whatsapp_web_session(
-    session_id: str,
-    user_id: str,
-) -> Dict[str, Any]:
-    """
-    Reconnect to an existing WhatsApp Web session using persisted browser data.
-
-    Use this after agent restart when the session data exists on disk
-    but the browser is no longer running.
-    """
-    manager = get_whatsapp_web_manager()
-    return await manager.reconnect_session(session_id, user_id)
-
-
-def list_persisted_whatsapp_web_sessions() -> List[Dict[str, Any]]:
-    """
-    List all WhatsApp Web sessions that have persisted data on disk.
-
-    These sessions can potentially be reconnected without a new QR scan
-    if the device is still linked on the phone.
-    """
-    manager = get_whatsapp_web_manager()
-    return manager.list_persisted_sessions()
-
-
-async def get_whatsapp_web_chat_messages(
-    session_id: str,
-    phone_number: str,
-    limit: int = 50,
-) -> Dict[str, Any]:
-    """Get recent messages from a specific chat via WhatsApp Web."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.get_chat_messages(session_id, phone_number, limit)
-    )
-
-
-async def get_whatsapp_web_chat_messages_by_name(
-    session_id: str,
-    chat_name: str,
-    limit: int = 50,
-) -> Dict[str, Any]:
-    """Get recent messages from a chat by clicking it in the sidebar (by name)."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.get_chat_messages_by_name(session_id, chat_name, limit)
-    )
-
-
-async def get_whatsapp_web_unread_chats(
-    session_id: str,
-) -> Dict[str, Any]:
-    """Get a list of chats that have unread messages via WhatsApp Web."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.get_unread_chats(session_id)
-    )
-
-
-async def get_whatsapp_web_own_profile_name(
-    session_id: str,
-) -> Optional[str]:
-    """Return the logged-in user's own WhatsApp display name, or *None*."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.get_own_profile_name(session_id)
-    )
-
-
-async def get_whatsapp_web_contact_phone(
-    session_id: str,
-    contact_name: str,
-) -> Dict[str, Any]:
-    """Resolve a contact name to a phone number via WhatsApp Web."""
-    manager = get_whatsapp_web_manager()
-    return await manager.run_on_playwright_loop(
-        manager.resolve_contact_phone(session_id, contact_name)
-    )
diff --git a/app/external_comms/registry.py b/app/external_comms/registry.py
deleted file mode 100644
index c55ed745..00000000
--- a/app/external_comms/registry.py
+++ /dev/null
@@ -1,78 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-app.external_comms.registry
-
-Simple registry of platform clients.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Dict, Optional, Type
-
-from app.external_comms.base import BasePlatformClient
-
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
-
-
-# Maps PLATFORM_ID -> client class
-_client_classes: Dict[str, Type[BasePlatformClient]] = {}
-
-# Maps PLATFORM_ID -> instantiated client (singletons)
-_client_instances: Dict[str, BasePlatformClient] = {}
-
-
-def register_client(client_cls: Type[BasePlatformClient]) -> Type[BasePlatformClient]:
-    """
-    Register a platform client class. Can be used as a decorator.
-
-    Usage:
-        @register_client
-        class SlackClient(BasePlatformClient):
-            PLATFORM_ID = "slack"
-    """
-    platform_id = client_cls.PLATFORM_ID
-    if not platform_id:
-        raise ValueError(f"{client_cls.__name__} has no PLATFORM_ID set")
-    _client_classes[platform_id] = client_cls
-    return client_cls
-
-
-def get_client(platform_id: str) -> Optional[BasePlatformClient]:
-    """
-    Get (or create) a singleton client instance by platform ID.
-
-    Returns None if the platform is not registered.
-    """
-    if platform_id in _client_instances:
-        return _client_instances[platform_id]
-
-    cls = _client_classes.get(platform_id)
-    if cls is None:
-        return None
-
-    instance = cls()
-    _client_instances[platform_id] = instance
-    return instance
-
-
-def get_all_clients() -> Dict[str, BasePlatformClient]:
-    """Get all registered client instances (instantiating as needed)."""
-    for platform_id in _client_classes:
-        if platform_id not in _client_instances:
-            _client_instances[platform_id] = _client_classes[platform_id]()
-    return dict(_client_instances)
-
-
-def get_registered_platforms() -> list[str]:
-    """Get list of all registered platform IDs."""
-    return list(_client_classes.keys())
-
-
-def reset() -> None:
-    """Clear all instances (useful for testing)."""
-    _client_instances.clear()
diff --git a/app/gui/gui_module.py b/app/gui/gui_module.py
index 37c5a6d2..616f7c97 100644
--- a/app/gui/gui_module.py
+++ b/app/gui/gui_module.py
@@ -81,8 +81,8 @@ def __init__(
         api_key = get_api_key(provider)
         base_url = get_base_url(provider)
 
-        self.llm: LLMInterface = LLMInterface(provider=provider, api_key=api_key, base_url=base_url)
-        self.vlm: VLMInterface = VLMInterface(provider=provider, api_key=api_key, base_url=base_url)
+        self.llm: LLMInterface = LLMInterface(provider=provider, api_key=api_key, base_url=base_url, deferred=not api_key)
+        self.vlm: VLMInterface = VLMInterface(provider=provider, api_key=api_key, base_url=base_url, deferred=not api_key)
         self.action_library: ActionLibrary = action_library
         self.action_router: ActionRouter = action_router
         self.context_engine: ContextEngine = context_engine
@@ -782,7 +782,8 @@ def _parse_reasoning_response(self, response: str) -> Tuple[ReasoningResult, int
         return reasoning_result, int(item_index)
 
     async def _check_agent_limits(self) -> bool:
-        agent_properties = STATE.get_agent_properties()
+        from app.state.agent_state import get_session_props
+        agent_properties = get_session_props().to_dict()
         action_count: int = agent_properties.get("action_count", 0)
         max_actions: int = agent_properties.get("max_actions_per_task", 0)
         token_count: int = agent_properties.get("token_count", 0)
diff --git a/app/living_ui/__init__.py b/app/living_ui/__init__.py
index fe6c59ec..2bf1a643 100644
--- a/app/living_ui/__init__.py
+++ b/app/living_ui/__init__.py
@@ -20,6 +20,7 @@
     register_broadcast_callbacks,
     broadcast_living_ui_ready,
     broadcast_living_ui_progress,
+    dispatch_living_ui_data_changed,
     make_todo_broadcast_hook,
 )
 from .actions import restart_living_ui
@@ -32,6 +33,7 @@
     'register_broadcast_callbacks',
     'broadcast_living_ui_ready',
     'broadcast_living_ui_progress',
+    'dispatch_living_ui_data_changed',
     'make_todo_broadcast_hook',
     'restart_living_ui',
 ]
diff --git a/app/living_ui/broadcast.py b/app/living_ui/broadcast.py
index c8304a71..d4de40fc 100644
--- a/app/living_ui/broadcast.py
+++ b/app/living_ui/broadcast.py
@@ -22,6 +22,7 @@
 _broadcast_ready_callback: Optional[Callable[[str, str, int], Awaitable[bool]]] = None
 _broadcast_progress_callback: Optional[Callable[[str, str, int, str], Awaitable[None]]] = None
 _broadcast_todos_callback: Optional[Callable[[str, List[Dict[str, Any]]], Awaitable[None]]] = None
+_broadcast_data_changed_callback: Optional[Callable[[str], Awaitable[None]]] = None
 
 # Captured at register time so cross-thread dispatchers (action handlers
 # running on a worker thread pool) can schedule coroutines onto the main loop.
@@ -32,15 +33,18 @@ def register_broadcast_callbacks(
     broadcast_ready: Callable[[str, str, int], Awaitable[bool]],
     broadcast_progress: Callable[[str, str, int, str], Awaitable[None]],
     broadcast_todos: Optional[Callable[[str, List[Dict[str, Any]]], Awaitable[None]]] = None,
+    broadcast_data_changed: Optional[Callable[[str], Awaitable[None]]] = None,
 ) -> None:
     """Register broadcast callbacks for Living UI actions to use.
 
     Called by the browser_adapter when it initializes.
     """
-    global _broadcast_ready_callback, _broadcast_progress_callback, _broadcast_todos_callback, _main_loop
+    global _broadcast_ready_callback, _broadcast_progress_callback, _broadcast_todos_callback
+    global _broadcast_data_changed_callback, _main_loop
     _broadcast_ready_callback = broadcast_ready
     _broadcast_progress_callback = broadcast_progress
     _broadcast_todos_callback = broadcast_todos
+    _broadcast_data_changed_callback = broadcast_data_changed
     try:
         _main_loop = asyncio.get_running_loop()
     except RuntimeError:
@@ -110,6 +114,44 @@ def _dispatch_todos(project_id: str, todos: List[Dict[str, Any]]) -> bool:
     return False
 
 
+async def _broadcast_data_changed_async(project_id: str) -> bool:
+    """Internal async broadcaster used by the sync dispatcher below."""
+    if _broadcast_data_changed_callback:
+        await _broadcast_data_changed_callback(project_id)
+        return True
+    return False
+
+
+def dispatch_living_ui_data_changed(project_id: str) -> bool:
+    """Thread-safe signal that a Living UI's data was modified by the agent.
+
+    Handles both calling contexts:
+      - Main asyncio loop: schedules via loop.create_task
+      - Worker thread: uses asyncio.run_coroutine_threadsafe against _main_loop
+
+    Returns True if the broadcast was scheduled, False otherwise.
+    """
+    if not _broadcast_data_changed_callback:
+        return False
+
+    coro = _broadcast_data_changed_async(project_id)
+
+    try:
+        running = asyncio.get_running_loop()
+        running.create_task(coro)
+        return True
+    except RuntimeError:
+        pass
+
+    if _main_loop is not None and _main_loop.is_running():
+        asyncio.run_coroutine_threadsafe(coro, _main_loop)
+        return True
+
+    coro.close()
+    logger.warning("[LIVING_UI] No main loop available; data-changed broadcast skipped")
+    return False
+
+
 def make_todo_broadcast_hook() -> Callable[[Any, List[Dict[str, Any]]], None]:
     """Build a post-update-todos hook that broadcasts todos for Living UI tasks.
 
diff --git a/app/living_ui/integration_bridge.py b/app/living_ui/integration_bridge.py
index d6312dd3..c1b071e0 100644
--- a/app/living_ui/integration_bridge.py
+++ b/app/living_ui/integration_bridge.py
@@ -62,7 +62,7 @@ async def _handle_available(self, request: web.Request) -> web.Response:
         if not project_id:
             return web.json_response({"error": "Unauthorized"}, status=401)
 
-        from app.external_comms.registry import get_registered_platforms, get_client
+        from craftos_integrations import get_registered_platforms, get_client
 
         integrations = []
         for platform_id in get_registered_platforms():
@@ -247,7 +247,7 @@ def _get_auth_headers(self, platform_id: str) -> Optional[dict]:
         Returns:
             Dict of auth headers, or None if credentials unavailable.
         """
-        from app.external_comms.registry import get_client
+        from craftos_integrations import get_client
 
         client = get_client(platform_id)
         if not client or not client.has_credentials():
diff --git a/app/llm/interface.py b/app/llm/interface.py
index b21fa5a8..dc6043ce 100644
--- a/app/llm/interface.py
+++ b/app/llm/interface.py
@@ -10,17 +10,17 @@
 
 from agent_core.core.impl.llm import LLMInterface as _LLMInterface
 from agent_core.core.hooks.types import UsageEventData
-from app.state.agent_state import STATE
+from app.state.agent_state import get_session_props
 
 
 def _get_token_count() -> int:
-    """Get token count from CraftBot's global STATE."""
-    return STATE.get_agent_property("token_count", 0)
+    """Get token count from the active task's StateSession (per-task counter)."""
+    return get_session_props().get_property("token_count", 0)
 
 
 def _set_token_count(count: int) -> None:
-    """Set token count in CraftBot's global STATE."""
-    STATE.set_agent_property("token_count", count)
+    """Set token count on the active task's StateSession (per-task counter)."""
+    get_session_props().set_property("token_count", count)
 
 
 async def _report_usage(event: UsageEventData) -> None:
@@ -59,3 +59,35 @@ def __init__(
             set_token_count=_set_token_count,
             report_usage=_report_usage,  # Report usage to local SQLite storage
         )
+
+    def _report_usage_async(
+        self,
+        service_type: str,
+        provider: str,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cached_tokens: int = 0,
+    ) -> None:
+        """Override: attribute to the active task SYNCHRONOUSLY at the call
+        site, then defer to the base for the async storage report.
+
+        The base implementation schedules the report hook as an asyncio task,
+        which means by the time the hook runs, STATE.current_task may have
+        already been swapped to a different task (or cleared) by a subsequent
+        trigger. Doing attribution synchronously here guarantees the counters
+        land on the task that actually made the LLM call.
+        """
+        from app.usage.task_attribution import attribute_usage_to_current_task
+        attribute_usage_to_current_task(UsageEventData(
+            service_type=service_type,
+            provider=provider,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+        ))
+        super()._report_usage_async(
+            service_type, provider, model,
+            input_tokens, output_tokens, cached_tokens,
+        )
diff --git a/app/llm_interface.py b/app/llm_interface.py
index 686ed9ab..d8299f19 100644
--- a/app/llm_interface.py
+++ b/app/llm_interface.py
@@ -37,7 +37,7 @@ class LLMCallType(str, Enum):
 from app.models.factory import ModelFactory
 from app.models.types import InterfaceType
 from app.google_gemini_client import GeminiAPIError, GeminiClient
-from app.state.agent_state import STATE
+from app.state.agent_state import STATE, get_session_props
 from agent_core import profile, OperationCategory
 
 # Logging setup — fall back to a basic logger if the project‑level logger
@@ -949,7 +949,8 @@ def _generate_response_sync(
         cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
 
         tokens_used = response.get("tokens_used", 0)
-        STATE.set_agent_property("token_count", STATE.get_agent_property("token_count", 0) + tokens_used)
+        _props = get_session_props()
+        _props.set_property("token_count", _props.get_property("token_count", 0) + tokens_used)
 
         if _slow_mode_active and tokens_used > 0:
             from app.rate_limiter import get_rate_limiter
@@ -1219,10 +1220,8 @@ def _generate_response_with_session_sync(
             response = self._generate_gemini(effective_system_prompt, user_prompt, call_type=call_type)
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1246,10 +1245,8 @@ def _generate_response_with_session_sync(
             response = self._generate_openai(effective_system_prompt, user_prompt, call_type=call_type)
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1334,10 +1331,8 @@ def _generate_response_with_session_sync(
 
             cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
             _tokens_used = response.get("tokens_used", 0)
-            STATE.set_agent_property(
-                "token_count",
-                STATE.get_agent_property("token_count", 0) + _tokens_used
-            )
+            _props = get_session_props(task_id)
+            _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
             if _slow_mode_active and _tokens_used > 0:
                 from app.rate_limiter import get_rate_limiter
                 get_rate_limiter().record_usage(_tokens_used)
@@ -1422,10 +1417,8 @@ def _generate_response_with_session_sync(
         cleaned = re.sub(self._CODE_BLOCK_RE, "", response.get("content", "").strip())
 
         _tokens_used = response.get("tokens_used", 0)
-        STATE.set_agent_property(
-            "token_count",
-            STATE.get_agent_property("token_count", 0) + _tokens_used
-        )
+        _props = get_session_props(task_id)
+        _props.set_property("token_count", _props.get_property("token_count", 0) + _tokens_used)
         if _slow_mode_active and _tokens_used > 0:
             from app.rate_limiter import get_rate_limiter
             get_rate_limiter().record_usage(_tokens_used)
diff --git a/app/onboarding/interfaces/steps.py b/app/onboarding/interfaces/steps.py
index d87c02aa..cc095cb2 100644
--- a/app/onboarding/interfaces/steps.py
+++ b/app/onboarding/interfaces/steps.py
@@ -109,6 +109,8 @@ class ProviderStep:
         ("byteplus", "BytePlus", "Kimi models"),
         ("anthropic", "Anthropic", "Claude models"),
         ("deepseek", "DeepSeek", "DeepSeek models"),
+        ("minimax", "MiniMax", "MiniMax models"),
+        ("moonshot", "Moonshot", "Moonshot models"),
         ("grok", "Grok (xAI)", "Grok models"),
         ("remote", "Ollama (Local)", "Self-hosted models"),
     ]
@@ -152,6 +154,8 @@ class ApiKeyStep:
         "byteplus": "BYTEPLUS_API_KEY",
         "anthropic": "ANTHROPIC_API_KEY",
         "deepseek": "DEEPSEEK_API_KEY",
+        "minimax": "MINIMAX_API_KEY",
+        "moonshot": "MOONSHOT_API_KEY",
         "grok": "XAI_API_KEY",
         "remote": None,  # Ollama uses a base URL, not an API key
     }
@@ -159,10 +163,17 @@ class ApiKeyStep:
     def __init__(self, provider: str = "openai"):
         self.provider = provider
 
+    # Providers that may be geo-restricted; support both direct and OpenRouter paths.
+    OPENROUTER_PROXIED = {"moonshot", "minimax"}
+    OPENROUTER_PROXIED_DISPLAY = {"moonshot": "Moonshot (Kimi)", "minimax": "MiniMax"}
+
     @property
     def title(self) -> str:
         if self.provider == "remote":
             return "Connect Ollama"
+        if self.provider in self.OPENROUTER_PROXIED:
+            display = self.OPENROUTER_PROXIED_DISPLAY.get(self.provider, self.provider)
+            return f"Enter {display} API Key"
         return "Enter API Key"
 
     @property
@@ -172,6 +183,12 @@ def description(self) -> str:
                 "Connect to your local Ollama instance.\n"
                 "If Ollama isn't installed yet, we'll help you set it up."
             )
+        if self.provider in self.OPENROUTER_PROXIED:
+            display = self.OPENROUTER_PROXIED_DISPLAY.get(self.provider, self.provider)
+            return (
+                f"Enter your {display} API key. If your region doesn't have direct access, "
+                f"you can use OpenRouter as a fallback instead."
+            )
         return "Enter your API key for the selected provider."
 
     def get_options(self) -> List[StepOption]:
@@ -188,6 +205,13 @@ def validate(self, value: Any) -> tuple[bool, Optional[str]]:
                 return False, "Please enter a valid URL (e.g. http://localhost:11434)"
             return True, None
 
+        # Proxied providers submit {api_key, via, or_model?} dict
+        if self.provider in self.OPENROUTER_PROXIED and isinstance(value, dict):
+            api_key = value.get("api_key", "")
+            if not api_key or len(str(api_key).strip()) < 10:
+                return False, "API key is required"
+            return True, None
+
         if not value or not isinstance(value, str):
             return False, "API key is required"
 
diff --git a/app/state/agent_state.py b/app/state/agent_state.py
index bb34686d..7e0ab37f 100644
--- a/app/state/agent_state.py
+++ b/app/state/agent_state.py
@@ -7,6 +7,7 @@
 from typing import Any, Dict, Optional
 from app.state.types import AgentProperties
 from app.task import Task
+from agent_core.core.state.session import StateSession
 
 @dataclass
 class AgentState:
@@ -16,6 +17,15 @@ class AgentState:
     event_stream: Optional[str] = None
     gui_mode: bool = False
     agent_properties: AgentProperties = AgentProperties(current_task_id="", action_count=0)
+    # UI event bus reference, set by the interface at boot so module-level
+    # hooks (e.g. _report_usage) can emit UI events without holding a
+    # controller handle. Typed Any to avoid pulling ui_layer into state.
+    event_bus: Any = None
+    # The agent's main asyncio event loop, captured when the interface
+    # adapter starts. Worker threads (e.g. LLM calls via asyncio.to_thread)
+    # use this to schedule coroutines back onto the loop via
+    # asyncio.run_coroutine_threadsafe. Typed Any to avoid importing asyncio.
+    main_loop: Any = None
 
     def update_current_task(self, new_task: Optional[Task]) -> None:
         self.current_task = new_task
@@ -58,3 +68,23 @@ def get_agent_properties(self):
 
 # ---- Global runtime state ----
 STATE = AgentState()
+
+
+def get_session_props(session_id: Optional[str] = None) -> AgentProperties:
+    """Return the AgentProperties bag that owns per-task counters
+    (token_count, action_count) for the active task.
+
+    If `session_id` is given, returns that session's properties; otherwise
+    uses STATE.agent_properties.current_task_id to find the active session.
+    Falls back to the global STATE.agent_properties when no session exists
+    (e.g. conversation mode or before a task is created).
+
+    This is the single source of truth for per-task counters — the global
+    STATE counters must not be used for limit checks or token attribution.
+    """
+    sid = session_id or STATE.agent_properties.get_property("current_task_id", "")
+    if sid:
+        session = StateSession.get_or_none(sid)
+        if session is not None:
+            return session.agent_properties
+    return STATE.agent_properties
diff --git a/app/tui/app.py b/app/tui/app.py
index af613cfe..88a886a8 100644
--- a/app/tui/app.py
+++ b/app/tui/app.py
@@ -18,7 +18,7 @@
 from app.models.types import InterfaceType
 
 from app.tui.styles import TUI_CSS
-from app.tui.settings import save_settings_to_json, get_api_key_env_name, get_api_key_for_provider
+from app.tui.settings import save_settings_to_json, get_api_key_for_provider
 from app.tui.widgets import ConversationLog, PasteableInput, VMFootageWidget, TaskSelected
 from app.tui.mcp_settings import (
     list_mcp_servers,
@@ -38,17 +38,20 @@
     install_skill_from_path,
     install_skill_from_git,
 )
-from app.external_comms.integration_settings import (
-    list_integrations,
-    get_integration_info,
+from craftos_integrations import (
+    autoload_integrations as _autoload_integrations,
+    connect_token as connect_integration_token,
+    connect_oauth as connect_integration_oauth,
+    connect_interactive as connect_integration_interactive,
+    disconnect as disconnect_integration,
     get_integration_fields,
-    get_integration_auth_type,
-    connect_integration_token,
-    connect_integration_oauth,
-    connect_integration_interactive,
-    disconnect_integration,
-    INTEGRATION_REGISTRY,
+    get_integration_info_sync as get_integration_info,
+    integration_registry,
+    list_integrations_sync as list_integrations,
 )
+
+_autoload_integrations()
+INTEGRATION_REGISTRY = integration_registry()
 from app.onboarding import onboarding_manager
 from app.logger import logger
 
diff --git a/app/tui/credential_commands.py b/app/tui/credential_commands.py
deleted file mode 100644
index 3ed84c97..00000000
--- a/app/tui/credential_commands.py
+++ /dev/null
@@ -1,32 +0,0 @@
-"""Credential TUI command functions. Returns tuple[bool, str] like mcp_settings.py."""
-from __future__ import annotations
-from typing import Tuple
-
-from app.credentials.handlers import INTEGRATION_HANDLERS, LOCAL_USER_ID
-
-
-def list_all_credentials() -> Tuple[bool, str]:
-    """List all stored credentials across integrations."""
-    lines = ["Stored Credentials:", ""]
-    found = False
-    for name, handler in INTEGRATION_HANDLERS.items():
-        try:
-            _, msg = __import__("asyncio").get_event_loop().run_until_complete(handler.status())
-            first_line = msg.split("\n")[0]
-            if "Not connected" not in first_line and "No " not in first_line:
-                found = True
-                lines.append(f"  {msg}")
-        except Exception:
-            pass
-    if not found:
-        return True, "No credentials stored. Use /<integration> login to connect."
-    return True, "\n".join(lines)
-
-
-def list_integrations() -> Tuple[bool, str]:
-    """List available integration types."""
-    lines = ["Available Integrations:", ""]
-    for name in INTEGRATION_HANDLERS:
-        lines.append(f"  /{name}")
-    lines.append("\nUse '/<name> login' to connect, '/<name> status' to check.")
-    return True, "\n".join(lines)
diff --git a/app/tui/integration_settings.py b/app/tui/integration_settings.py
deleted file mode 100644
index fb994abc..00000000
--- a/app/tui/integration_settings.py
+++ /dev/null
@@ -1,18 +0,0 @@
-"""Backwards-compatible re-export — real module lives in app.external_comms.integration_settings."""
-from app.external_comms.integration_settings import *  # noqa: F401,F403
-from app.external_comms.integration_settings import (  # explicit re-exports for type checkers
-    INTEGRATION_REGISTRY,
-    PLATFORM_MAP,
-    list_integrations,
-    get_integration_info,
-    get_integration_accounts,
-    get_integration_auth_type,
-    get_integration_fields,
-    connect_integration_token,
-    connect_integration_oauth,
-    connect_integration_interactive,
-    disconnect_integration,
-    start_whatsapp_qr_session,
-    check_whatsapp_session_status,
-    cancel_whatsapp_session,
-)
diff --git a/app/tui/settings.py b/app/tui/settings.py
index dc45304c..a0940414 100644
--- a/app/tui/settings.py
+++ b/app/tui/settings.py
@@ -19,7 +19,10 @@
     "byteplus": "byteplus",
     "anthropic": "anthropic",
     "deepseek": "deepseek",
+    "minimax": "minimax",
+    "moonshot": "moonshot",
     "grok": "grok",
+    "openrouter": "openrouter",
 }
 
 
diff --git a/app/ui_layer/adapters/base.py b/app/ui_layer/adapters/base.py
index 23a03123..1b7bd562 100644
--- a/app/ui_layer/adapters/base.py
+++ b/app/ui_layer/adapters/base.py
@@ -138,6 +138,14 @@ async def start(self) -> None:
         self._running = True
         self._controller.register_adapter(self)
 
+        # Capture the main event loop so worker threads (LLM calls invoked
+        # via asyncio.to_thread) can schedule coroutines back onto it.
+        try:
+            from app.state.agent_state import STATE
+            STATE.main_loop = asyncio.get_running_loop()
+        except Exception:
+            pass
+
         # Subscribe to events
         self._subscribe_events()
 
@@ -242,6 +250,9 @@ def _subscribe_events(self) -> None:
         self._unsubscribers.append(
             bus.subscribe(UIEventType.TASK_UPDATE, self._handle_task_update)
         )
+        self._unsubscribers.append(
+            bus.subscribe(UIEventType.TASK_TOKEN_UPDATE, self._handle_task_token_update)
+        )
 
         # Footage events
         self._unsubscribers.append(
@@ -348,6 +359,20 @@ def _handle_task_start(self, event: UIEvent) -> None:
         if not task_id:
             return
 
+        # Look up the source Task to capture skill/workflow context for the UI
+        selected_skills: List[str] = []
+        workflow_id: Optional[str] = None
+        try:
+            agent = getattr(self._controller, "agent", None)
+            task_manager = getattr(agent, "task_manager", None) if agent else None
+            if task_manager is not None:
+                task = task_manager.get_task_by_id(task_id)
+                if task is not None:
+                    selected_skills = list(task.selected_skills or [])
+                    workflow_id = task.workflow_id
+        except Exception:
+            pass
+
         if self.action_panel:
             asyncio.create_task(
                 self.action_panel.add_item(
@@ -356,6 +381,8 @@ def _handle_task_start(self, event: UIEvent) -> None:
                         name=event.data.get("task_name", "Task"),
                         status="running",
                         item_type="task",
+                        selected_skills=selected_skills,
+                        workflow_id=workflow_id,
                     )
                 )
             )
@@ -451,6 +478,39 @@ def _handle_task_update(self, event: UIEvent) -> None:
                 self.action_panel.update_item(task_id, status)
             )
 
+    def _handle_task_token_update(self, event: UIEvent) -> None:
+        """Handle per-task token-usage tick - push running totals to the panel.
+
+        This handler can be invoked from a worker thread (LLM calls run via
+        asyncio.to_thread, so _report_usage_async fires off-loop). On a
+        worker thread asyncio.create_task raises RuntimeError because there
+        is no running loop, so we must dispatch to the main loop explicitly.
+        """
+        task_id = event.data.get("task_id", "")
+        if not (task_id and self.action_panel):
+            return
+
+        coro = self.action_panel.update_item_tokens(
+            task_id,
+            int(event.data.get("input_tokens", 0)),
+            int(event.data.get("output_tokens", 0)),
+            int(event.data.get("cache_tokens", 0)),
+        )
+
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(coro)
+        except RuntimeError:
+            # Called from a worker thread (typical for LLM result reporting).
+            # Schedule onto the main loop captured at adapter start.
+            from app.state.agent_state import STATE
+            main_loop = STATE.main_loop
+            if main_loop is not None and not main_loop.is_closed():
+                asyncio.run_coroutine_threadsafe(coro, main_loop)
+            else:
+                # Avoid "coroutine was never awaited" warning if we can't dispatch
+                coro.close()
+
     def _handle_footage_update(self, event: UIEvent) -> None:
         """Handle footage update event."""
         if self.footage_component:
diff --git a/app/ui_layer/adapters/browser_adapter.py b/app/ui_layer/adapters/browser_adapter.py
index 68014828..ebdbfc38 100644
--- a/app/ui_layer/adapters/browser_adapter.py
+++ b/app/ui_layer/adapters/browser_adapter.py
@@ -6,8 +6,11 @@
 import base64
 import json
 import os
+import re
 import shutil
 import time
+import uuid
+from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set
 
@@ -430,6 +433,11 @@ def _init_storage(self) -> None:
                     input_data=stored.input_data,
                     output_data=stored.output_data,
                     error_message=stored.error_message,
+                    selected_skills=list(stored.selected_skills or []),
+                    workflow_id=stored.workflow_id,
+                    input_tokens=stored.input_tokens,
+                    output_tokens=stored.output_tokens,
+                    cache_tokens=stored.cache_tokens,
                 ))
         except Exception:
             # Storage may not be available, continue without persistence
@@ -451,6 +459,11 @@ def _persist_item(self, item: ActionItem) -> None:
                     input_data=item.input_data,
                     output_data=item.output_data,
                     error_message=item.error_message,
+                    selected_skills=list(item.selected_skills or []),
+                    workflow_id=item.workflow_id,
+                    input_tokens=item.input_tokens,
+                    output_tokens=item.output_tokens,
+                    cache_tokens=item.cache_tokens,
                 )
                 self._storage.insert_item(stored)
             except Exception:
@@ -484,6 +497,11 @@ async def add_item(self, item: ActionItem) -> None:
                 "input": item.input_data,
                 "output": item.output_data,
                 "error": item.error_message,
+                "selectedSkills": list(item.selected_skills or []),
+                "workflowId": item.workflow_id,
+                "inputTokens": item.input_tokens,
+                "outputTokens": item.output_tokens,
+                "cacheTokens": item.cache_tokens,
             },
         })
 
@@ -581,6 +599,49 @@ async def update_item_by_name(
                 },
             })
 
+    async def update_item_tokens(
+        self,
+        item_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        cache_tokens: int,
+    ) -> None:
+        """Update a task item's cumulative token counters and broadcast."""
+        from app.logger import logger
+
+        matched_item = None
+        for item in self._items:
+            if item.id == item_id:
+                item.input_tokens = input_tokens
+                item.output_tokens = output_tokens
+                item.cache_tokens = cache_tokens
+                matched_item = item
+                break
+
+        if matched_item:
+            # Persist update to storage so totals survive a refresh/restart
+            self._persist_item(matched_item)
+
+            await self._adapter._broadcast({
+                "type": "task_token_update",
+                "data": {
+                    "id": item_id,
+                    "inputTokens": input_tokens,
+                    "outputTokens": output_tokens,
+                    "cacheTokens": cache_tokens,
+                },
+            })
+            logger.debug(
+                f"[TOKEN_UI] broadcast task_token_update id={item_id} "
+                f"in={input_tokens} out={output_tokens} cache={cache_tokens}"
+            )
+        else:
+            logger.warning(
+                f"[TOKEN_UI] update_item_tokens: no ActionItem in panel for id={item_id} "
+                f"(panel has {len(self._items)} items). "
+                f"Token attribution will be invisible to the UI until the task is added."
+            )
+
     async def update_item_data(
         self,
         item_id: str,
@@ -644,6 +705,57 @@ async def clear(self) -> None:
             "type": "action_clear",
         })
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks remain visible.
+
+        Returns:
+            Number of tasks removed (does not count child actions).
+        """
+        terminal_statuses = {"completed", "error", "cancelled"}
+
+        # Find terminal task IDs in the in-memory list
+        terminal_task_ids = {
+            item.id
+            for item in self._items
+            if item.item_type == "task" and item.status in terminal_statuses
+        }
+
+        if not terminal_task_ids:
+            return 0
+
+        # Remove the tasks themselves and any actions that belong to them
+        removed_ids = [
+            item.id
+            for item in self._items
+            if item.id in terminal_task_ids or item.parent_id in terminal_task_ids
+        ]
+        self._items = [
+            item
+            for item in self._items
+            if item.id not in terminal_task_ids and item.parent_id not in terminal_task_ids
+        ]
+
+        # Mirror in storage so a refresh doesn't bring them back. We let
+        # storage compute its own ID set rather than pass our list, since
+        # storage may carry tasks not currently loaded in memory.
+        if self._storage:
+            try:
+                self._storage.clear_terminal_tasks()
+            except Exception:
+                pass
+
+        # Tell each connected client to drop the removed items individually,
+        # so any other (running) tasks they're watching stay in place.
+        for item_id in removed_ids:
+            await self._adapter._broadcast({
+                "type": "action_remove",
+                "data": {"id": item_id},
+            })
+
+        return len(terminal_task_ids)
+
     def select_task(self, task_id: Optional[str]) -> None:
         """Select task - handled by frontend."""
         pass
@@ -816,6 +928,7 @@ def __init__(
             broadcast_ready=self.broadcast_living_ui_ready,
             broadcast_progress=self.broadcast_living_ui_progress,
             broadcast_todos=self.broadcast_living_ui_todos,
+            broadcast_data_changed=self.broadcast_living_ui_data_changed,
         )
 
         # Subscribe the Living UI module to TaskManager todo updates so that
@@ -1118,6 +1231,10 @@ async def _websocket_handler(self, request: "web.Request") -> "web.WebSocketResp
                 "type": "init",
                 "data": initial_state,
             })
+            await ws.send_json({
+                "type": "skill_meta",
+                "data": self._get_skill_meta(),
+            })
         except (ConnectionResetError, ClientConnectionResetError, RuntimeError) as e:
             # Gracefully handle connection closing
             self._ws_clients.discard(ws)
@@ -1314,6 +1431,15 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
         elif msg_type == "reset":
             await self._handle_reset()
 
+        elif msg_type == "clear_conversation":
+            await self._handle_clear_conversation()
+
+        elif msg_type == "clear_tasks":
+            await self._handle_clear_tasks()
+
+        elif msg_type == "create_skill_from_task":
+            await self._handle_create_skill_from_task(data)
+
         # Scheduler/Proactive operations
         elif msg_type == "scheduler_config_get":
             await self._handle_scheduler_config_get()
@@ -1401,7 +1527,8 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
             provider = data.get("provider", "")
             api_key = data.get("apiKey")
             base_url = data.get("baseUrl")
-            await self._handle_model_connection_test(provider, api_key, base_url)
+            model = data.get("model")
+            await self._handle_model_connection_test(provider, api_key, base_url, model)
 
         elif msg_type == "model_validate_save":
             await self._handle_model_validate_save(data)
@@ -1410,6 +1537,18 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
             base_url = data.get("baseUrl")
             await self._handle_ollama_models_get(base_url)
 
+        elif msg_type == "openrouter_models_get":
+            await self._handle_openrouter_models_get(
+                base_url=data.get("baseUrl"),
+                force_refresh=bool(data.get("forceRefresh", False)),
+            )
+
+        elif msg_type == "openrouter_credits_get":
+            await self._handle_openrouter_credits_get(
+                api_key=data.get("apiKey"),
+                base_url=data.get("baseUrl"),
+            )
+
         elif msg_type == "slow_mode_get":
             await self._handle_slow_mode_get()
 
@@ -1523,33 +1662,20 @@ async def _handle_ws_message(self, data: Dict[str, Any], ws=None) -> None:
             account_id = data.get("account_id")
             await self._handle_integration_disconnect(integration_id, account_id)
 
-        # Jira settings handlers
-        elif msg_type == "jira_get_settings":
-            await self._handle_jira_get_settings()
-
-        elif msg_type == "jira_update_settings":
-            watch_tag = data.get("watch_tag")
-            watch_labels = data.get("watch_labels")
-            await self._handle_jira_update_settings(watch_tag=watch_tag, watch_labels=watch_labels)
-
-        # GitHub settings handlers
-        elif msg_type == "github_get_settings":
-            await self._handle_github_get_settings()
+        # Generic per-integration config (replaces the old bespoke jira/github settings handlers)
+        elif msg_type == "integration_get_config":
+            integration_id = data.get("id")
+            await self._handle_integration_get_config(integration_id)
 
-        elif msg_type == "github_update_settings":
-            watch_tag = data.get("watch_tag")
-            watch_repos = data.get("watch_repos")
-            await self._handle_github_update_settings(watch_tag=watch_tag, watch_repos=watch_repos)
+        elif msg_type == "integration_update_config":
+            integration_id = data.get("id")
+            values = data.get("values") or {}
+            await self._handle_integration_update_config(integration_id, values)
 
         # Living UI settings handlers
         elif msg_type == "living_ui_settings_get":
             await self._handle_living_ui_settings_get()
 
-        elif msg_type == "living_ui_project_action":
-            project_id = data.get("projectId", "")
-            action = data.get("action", "")
-            await self._handle_living_ui_project_action(project_id, action)
-
         elif msg_type == "living_ui_project_setting_update":
             project_id = data.get("projectId", "")
             setting = data.get("setting", "")
@@ -1867,17 +1993,56 @@ async def _handle_onboarding_step_submit(self, value: Any) -> None:
                     # Normalise the value to the URL that actually worked
                     value = ollama_url
                 elif value:
-                    test_result = test_connection(
-                        provider=provider,
-                        api_key=value,
-                    )
+                    from app.models import MODEL_REGISTRY, InterfaceType
+                    from app.onboarding.interfaces.steps import ApiKeyStep
+                    # For proxied providers, value is a dict {api_key, via, or_model?}.
+                    # via='direct' → test the provider's own endpoint.
+                    # via='openrouter' → test via OpenRouter proxy.
+                    if provider in ApiKeyStep.OPENROUTER_PROXIED:
+                        if isinstance(value, dict):
+                            actual_key = value.get("api_key", "")
+                            via = value.get("via", "openrouter")
+                            or_model = value.get("or_model", "")
+                        else:
+                            actual_key = value
+                            via = "direct"
+                            or_model = ""
+
+                        if via == "openrouter":
+                            if not or_model:
+                                from agent_core.core.models.factory import _OR_MODEL_MAP, _to_openrouter_slug
+                                native_model = MODEL_REGISTRY.get(provider, {}).get(InterfaceType.LLM, "")
+                                or_model = _OR_MODEL_MAP.get(provider, {}).get(native_model) or _to_openrouter_slug(provider, native_model)
+                            test_result = test_connection(
+                                provider="openrouter",
+                                api_key=actual_key,
+                                model=or_model,
+                            )
+                        else:
+                            # Direct API test
+                            native_model = MODEL_REGISTRY.get(provider, {}).get(InterfaceType.LLM)
+                            test_result = test_connection(
+                                provider=provider,
+                                api_key=actual_key,
+                                model=native_model,
+                            )
+                        # Store via + resolved or_model so _complete() knows how to save
+                        value = {"api_key": actual_key, "via": via, "or_model": or_model}
+                    else:
+                        actual_key = value if isinstance(value, str) else value.get("api_key", "")
+                        default_model = MODEL_REGISTRY.get(provider, {}).get(InterfaceType.LLM)
+                        test_result = test_connection(
+                            provider=provider,
+                            api_key=actual_key,
+                            model=default_model,
+                        )
                     if not test_result.get("success"):
                         error_msg = test_result.get("error") or test_result.get("message") or "Connection test failed"
                         await self._broadcast({
                             "type": "onboarding_submit",
                             "data": {
                                 "success": False,
-                                "error": f"Invalid API key: {error_msg}",
+                                "error": error_msg,
                                 "index": controller.current_step_index,
                             },
                         })
@@ -2615,6 +2780,14 @@ async def broadcast_living_ui_todos(
             },
         })
 
+    async def broadcast_living_ui_data_changed(self, project_id: str) -> None:
+        """Tell the browser that a Living UI's backend data was just modified
+        by the agent, so it should refresh the iframe to display new state."""
+        await self._broadcast({
+            "type": "living_ui_data_changed",
+            "data": {"projectId": project_id},
+        })
+
     async def _handle_task_cancel(self, task_id: str) -> None:
         """Cancel a running task."""
         try:
@@ -2674,6 +2847,14 @@ async def _handle_option_click(self, value: str, session_id: str, message_id: st
                         m.option_selected = value
                         break
 
+            # Navigate to model settings page
+            if value == "llm_change_model":
+                await self._broadcast({
+                    "type": "navigate",
+                    "data": {"path": "/settings"},
+                })
+                return
+
             # Route to the controller
             await self._controller.handle_option_click(value, session_id)
         except Exception as e:
@@ -2853,6 +3034,534 @@ async def _handle_reset(self) -> None:
                 },
             })
 
+    async def _handle_clear_conversation(self) -> None:
+        """
+        Clear the chat conversation log only.
+
+        Drops chat messages from the panel and from chat_storage. The
+        action panel (tasks/actions) is left alone so running tasks are
+        not disrupted. Dashboard usage/task metrics live in a separate
+        database and are not touched.
+        """
+        try:
+            await self._chat.clear()
+            await self._broadcast({
+                "type": "clear_conversation",
+                "data": {"success": True},
+            })
+        except Exception as e:
+            await self._broadcast({
+                "type": "clear_conversation",
+                "data": {"success": False, "error": str(e)},
+            })
+
+    async def _handle_clear_tasks(self) -> None:
+        """
+        Clear only finished tasks (completed/error/cancelled) and their
+        child actions from the panel. Running/waiting tasks are preserved.
+
+        Dashboard usage/task metrics are persisted in a separate database
+        and are not affected.
+        """
+        try:
+            removed = await self._action_panel.clear_terminal_tasks()
+            await self._broadcast({
+                "type": "clear_tasks",
+                "data": {"success": True, "removed": removed},
+            })
+        except Exception as e:
+            await self._broadcast({
+                "type": "clear_tasks",
+                "data": {"success": False, "error": str(e)},
+            })
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Skill creation from a completed task
+    # ─────────────────────────────────────────────────────────────────────
+
+    # `workflow_id` is functional infrastructure, NOT a "this task is
+    # internal" tag. It is set only on workflows that need:
+    #   1. WorkflowLockManager serialization (memory_processing — only
+    #      one memory pass at a time; the lock is auto-released in
+    #      TaskManager._end_task by keying off task.workflow_id).
+    #   2. Post-completion side effects (skill_creation / skill_improvement
+    #      trigger SkillManager.reload() and auto-enable the new skill in
+    #      TaskManager._end_task).
+    # Tasks tagged with one of these are internal by definition (they ARE
+    # the skill / memory infrastructure) and must never be eligible as
+    # source tasks for the "Create Skill" flow. Heartbeats, planners, and
+    # the onboarding interview don't need either of those two services, so
+    # they don't set workflow_id — _INTERNAL_SKILL_NAMES covers them.
+    _INTERNAL_WORKFLOW_IDS = frozenset({
+        "skill_creation",
+        "skill_improvement",
+        "memory_processing",
+    })
+
+    # Detection of internal tasks via `selected_skills` — needed because
+    # most internal workflows (heartbeats, planners, soft onboarding) only
+    # set selected_skills, not workflow_id. This is the union of every
+    # skill in the repo with `user-invocable: false`. A task whose
+    # selected_skills intersects this set is system-spawned and the
+    # "Create Skill" button must not appear on it.
+    # Used together with _INTERNAL_WORKFLOW_IDS via OR — see the frontend
+    # `isInternalWorkflowTask` for the combined check.
+    _INTERNAL_SKILL_NAMES = frozenset({
+        "craftbot-skill-creator",
+        "craftbot-skill-improve",
+        "memory-processor",
+        "heartbeat-processor",
+        "user-profile-interview",
+        "day-planner",
+        "week-planner",
+        "month-planner",
+    })
+
+    # Names the user may not type into the SkillCreatorModal (validated in
+    # _handle_create_skill_from_task). Kept separate from
+    # _INTERNAL_SKILL_NAMES because the two answer different questions:
+    #   _INTERNAL_SKILL_NAMES → "is this *task* a system task?" (hides the
+    #     Create Skill button on its detail panel)
+    #   _RESERVED_SKILL_NAMES → "is this *name* one the user can claim?"
+    #     (modal input validation)
+    # The contents happen to coincide today, but a future user-invocable
+    # skill that we still don't want overwritten would belong only here,
+    # and an internal skill we'd let users replace would belong only in
+    # _INTERNAL_SKILL_NAMES — keeping them split avoids a re-split later.
+    _RESERVED_SKILL_NAMES = frozenset({
+        "craftbot-skill-creator",
+        "craftbot-skill-improve",
+        "memory-processor",
+        "user-profile-interview",
+        "heartbeat-processor",
+        "day-planner",
+        "week-planner",
+        "month-planner",
+    })
+
+    _SKILL_NAME_PATTERN = re.compile(r"^[a-z][a-z0-9-]{1,63}$")
+
+    def _get_skill_meta(self) -> Dict[str, Any]:
+        return {
+            "internalWorkflowIds": sorted(self._INTERNAL_WORKFLOW_IDS),
+            "internalSkillNames": sorted(self._INTERNAL_SKILL_NAMES),
+            "reservedSkillNames": sorted(self._RESERVED_SKILL_NAMES),
+        }
+
+    async def _handle_create_skill_from_task(self, data: Dict[str, Any]) -> None:
+        """
+        Spawn a workflow task that creates or improves a skill, using a
+        completed source task as evidence. Writes a per-task SKILL_SOURCE
+        markdown file before queueing the trigger.
+        """
+        response_type = "create_skill_from_task"
+
+        async def _err(msg: str) -> None:
+            await self._broadcast({
+                "type": response_type,
+                "data": {"success": False, "error": msg},
+            })
+
+        # ---- Validate request shape ----------------------------------
+        source_task_id = (data.get("taskId") or "").strip()
+        mode = data.get("mode")
+        skill_name_raw = (data.get("skillName") or "").strip()
+        target_skill_raw = (data.get("targetSkill") or "").strip()
+
+        # `verb` is the imperative form used inside the agent's instruction
+        # string ("Create skill 'x'."). `task_title_verb` is the progressive
+        # form used in the user-facing task title shown in the action panel
+        # ("Creating skill: x") so users see what the agent is *doing*, not
+        # a command at them.
+        if mode == "create":
+            workflow_id = "skill_creation"
+            workflow_skill = "craftbot-skill-creator"
+            target = skill_name_raw
+            verb = "Create"
+            task_title_verb = "Creating"
+        elif mode == "improve":
+            workflow_id = "skill_improvement"
+            workflow_skill = "craftbot-skill-improve"
+            target = target_skill_raw
+            verb = "Improve"
+            task_title_verb = "Improving"
+        else:
+            await _err("invalid_mode")
+            return
+
+        if not source_task_id:
+            await _err("missing_task_id")
+            return
+        if not target:
+            await _err("missing_skill_name")
+            return
+        if not self._SKILL_NAME_PATTERN.fullmatch(target):
+            await _err("invalid_skill_name")
+            return
+        if target in self._RESERVED_SKILL_NAMES:
+            await _err("reserved_skill_name")
+            return
+
+        # ---- Look up source task -------------------------------------
+        # The in-memory `task_manager.tasks` dict only holds RUNNING tasks —
+        # `_finalize_task` pops the entry when a task ends. So a completed
+        # source task is never resolvable via `get_task_by_id`. Source from
+        # the durable ActionItem record instead (in-memory panel first, then
+        # `actions.db` SQLite as fallback). Both paths carry `selected_skills`
+        # and `workflow_id` thanks to the earlier payload extension.
+        agent = self._controller.agent
+        task_manager = getattr(agent, "task_manager", None)
+        if task_manager is None:
+            await _err("task_manager_unavailable")
+            return
+
+        source_item = self._lookup_source_action_item(source_task_id)
+        if source_item is None:
+            await _err("source_task_not_found")
+            return
+        if source_item.item_type != "task":
+            await _err("source_task_not_found")
+            return
+        if source_item.status != "completed":
+            await _err("source_task_not_completed")
+            return
+        # Reject any task that is itself a CraftBot internal workflow.
+        # Two signals — either is sufficient:
+        #   1. `workflow_id` matches a known internal id (memory processing,
+        #      skill creation/improvement)
+        #   2. `selected_skills` intersects the user-invocable:false skill
+        #      set (soft onboarding, heartbeat, planners — these don't set
+        #      workflow_id, only selected_skills)
+        if (source_item.workflow_id or "") in self._INTERNAL_WORKFLOW_IDS:
+            await _err("source_task_is_internal_workflow")
+            return
+        if any(s in self._INTERNAL_SKILL_NAMES for s in (source_item.selected_skills or [])):
+            await _err("source_task_is_internal_workflow")
+            return
+
+        # ---- Skill existence checks ----------------------------------
+        skills_dir = Path(__file__).resolve().parents[3] / "skills"
+        target_dir = skills_dir / target
+        target_skill_md = target_dir / "SKILL.md"
+
+        if mode == "create":
+            if target_skill_md.exists():
+                await _err("skill_already_exists")
+                return
+            try:
+                from app.tui.skill_settings import get_skill_info
+                if get_skill_info(target):
+                    await _err("skill_already_exists")
+                    return
+            except Exception:
+                pass
+        else:  # improve
+            if not target_skill_md.exists():
+                await _err("skill_not_found")
+                return
+
+        # ---- Acquire workflow lock -----------------------------------
+        lock_manager = getattr(agent, "workflow_lock_manager", None)
+        if lock_manager is None:
+            await _err("workflow_lock_unavailable")
+            return
+        if not await lock_manager.try_acquire(workflow_id):
+            await _err("workflow_busy")
+            return
+
+        new_task_id = uuid.uuid4().hex
+        source_md_path: Optional[Path] = None
+        try:
+            # ---- Build SKILL_SOURCE_<id>.md --------------------------
+            from app.config import AGENT_FILE_SYSTEM_PATH
+            source_md_path = Path(AGENT_FILE_SYSTEM_PATH) / f"SKILL_SOURCE_{new_task_id}.md"
+            source_md_path.parent.mkdir(parents=True, exist_ok=True)
+            existing_skill_md = target_skill_md if mode == "improve" else None
+            source_md_path.write_text(
+                self._build_skill_source_md(
+                    mode=mode,
+                    target_skill=target,
+                    source_item=source_item,
+                    existing_skill_md=existing_skill_md,
+                ),
+                encoding="utf-8",
+            )
+
+            # ---- Ensure the workflow skill is enabled ----------------
+            try:
+                enable_skill(workflow_skill)
+            except Exception as e:
+                logger.debug(f"[SKILL_CREATOR] enable_skill({workflow_skill}) noop/failed: {e}")
+
+            # ---- Spawn the workflow task -----------------------------
+            # Use absolute paths in the instruction so the agent can pass
+            # them verbatim to read_file / write_file / stream_edit. With
+            # relative paths (e.g. "skills/<name>/SKILL.md") the agent has
+            # been observed mistakenly prepending the source-file's prefix
+            # (`agent_file_system/`), landing the new SKILL.md inside the
+            # agent file system instead of the project's `skills/` dir.
+            absolute_source_path = source_md_path.resolve()
+            absolute_target_path = target_skill_md.resolve()
+            instruction = (
+                f"SILENT BACKGROUND TASK — do not message the user.\n"
+                f"{verb} skill '{target}'.\n"
+                f"Source file (read this — absolute path, use verbatim): {absolute_source_path}\n"
+                f"Target file (write the new SKILL.md here — absolute path, use verbatim): {absolute_target_path}\n"
+                f"Mode: {mode}\n"
+                f"Skill name: {target}\n"
+                f"Read the source file, follow the {workflow_skill} skill instructions, "
+                f"write the new skill to the target file (use the absolute target path verbatim), "
+                f"and end the task with task_end."
+            )
+            # No colon in the title — EventTransformer._create_task_start_event
+            # splits on the first ":" and keeps only the suffix, which would
+            # otherwise leave the panel showing just the bare skill name.
+            task_name = f'{task_title_verb} skill "{target}"'
+            task_manager.create_task(
+                task_name=task_name,
+                task_instruction=instruction,
+                mode="complex",
+                action_sets=["file_operations"],
+                selected_skills=[workflow_skill],
+                session_id=new_task_id,
+                workflow_id=workflow_id,
+            )
+
+            # ---- Queue trigger so execution actually starts ---------
+            from app.trigger import Trigger
+            trigger = Trigger(
+                fire_at=time.time(),
+                priority=60,
+                next_action_description=f"{verb} skill '{target}' from completed task",
+                session_id=new_task_id,
+                payload={},
+            )
+            await agent.triggers.put(trigger)
+
+            # Acknowledge in the chat immediately so the user sees the work
+            # being picked up. The agent will follow up with a presentation
+            # message when the workflow completes (see craftbot-skill-* SKILL.md).
+            ack_text = (
+                f"Creating skill `{target}` from the completed task."
+                if mode == "create"
+                else f"Improving skill `{target}` based on the recent task."
+            )
+            try:
+                await self._display_chat_message("System", ack_text, "system")
+            except Exception as e:
+                logger.debug(f"[SKILL_CREATOR] ack chat message failed: {e}")
+
+            await self._broadcast({
+                "type": response_type,
+                "data": {
+                    "success": True,
+                    "taskId": new_task_id,
+                    "skillName": target,
+                    "mode": mode,
+                },
+            })
+            return
+
+        except Exception as e:
+            logger.warning(f"[SKILL_CREATOR] handler failed: {e}", exc_info=True)
+            # Release the lock since the task never took ownership.
+            try:
+                await lock_manager.release(workflow_id)
+            except Exception:
+                pass
+            # Best-effort cleanup of the source file we wrote.
+            if source_md_path is not None:
+                try:
+                    source_md_path.unlink()
+                except Exception:
+                    pass
+            await _err(str(e) or "internal_error")
+            return
+
+    def _lookup_source_action_item(self, item_id: str) -> Optional[ActionItem]:
+        """Find a task-level ActionItem by id.
+
+        Tries the in-memory action panel first (fastest, current session),
+        then falls back to ActionStorage (`actions.db`) so completed tasks
+        from previous sessions still resolve. Both sources carry
+        `selected_skills` and `workflow_id` after the payload extension.
+        """
+        # In-memory first
+        try:
+            for item in (self._action_panel._items if self._action_panel else []):
+                if item.id == item_id:
+                    return item
+        except Exception:
+            pass
+
+        # SQLite fallback
+        try:
+            storage = getattr(self._action_panel, "_storage", None) if self._action_panel else None
+            if storage is not None:
+                stored = storage.get_item(item_id)
+                if stored is not None:
+                    return ActionItem(
+                        id=stored.id,
+                        name=stored.name,
+                        status=stored.status,
+                        item_type=stored.item_type,
+                        parent_id=stored.parent_id,
+                        created_at=stored.created_at,
+                        completed_at=stored.completed_at,
+                        input_data=stored.input_data,
+                        output_data=stored.output_data,
+                        error_message=stored.error_message,
+                        selected_skills=list(stored.selected_skills or []),
+                        workflow_id=stored.workflow_id,
+                    )
+        except Exception:
+            pass
+
+        return None
+
+    def _gather_child_action_items(self, parent_id: str) -> List[ActionItem]:
+        """Collect every child ActionItem under `parent_id`, deduped by id.
+
+        Pulls from in-memory first, then ActionStorage. Result is sorted by
+        creation time. The two sources usually overlap completely; the union
+        is the safe choice for a task that just completed (in-memory has the
+        absolute-latest state) or one that was loaded from disk after a
+        restart (storage is the only source).
+        """
+        seen_ids: Set[str] = set()
+        children: List[ActionItem] = []
+
+        try:
+            for item in (self._action_panel._items if self._action_panel else []):
+                if item.parent_id == parent_id and item.id not in seen_ids:
+                    children.append(item)
+                    seen_ids.add(item.id)
+        except Exception:
+            pass
+
+        try:
+            storage = getattr(self._action_panel, "_storage", None) if self._action_panel else None
+            if storage is not None:
+                for sit in storage.get_items(limit=2000, include_running=True):
+                    if sit.parent_id == parent_id and sit.id not in seen_ids:
+                        children.append(ActionItem(
+                            id=sit.id,
+                            name=sit.name,
+                            status=sit.status,
+                            item_type=sit.item_type,
+                            parent_id=sit.parent_id,
+                            created_at=sit.created_at,
+                            completed_at=sit.completed_at,
+                            input_data=sit.input_data,
+                            output_data=sit.output_data,
+                            error_message=sit.error_message,
+                            selected_skills=list(sit.selected_skills or []),
+                            workflow_id=sit.workflow_id,
+                        ))
+                        seen_ids.add(sit.id)
+        except Exception:
+            pass
+
+        children.sort(key=lambda it: it.created_at or 0.0)
+        return children
+
+    def _build_skill_source_md(
+        self,
+        *,
+        mode: str,
+        target_skill: str,
+        source_item: ActionItem,
+        existing_skill_md: Optional[Path],
+    ) -> str:
+        """Compose the per-task SKILL_SOURCE markdown file from durable
+        ActionItem records (the live `Task` object is gone by the time the
+        user clicks Create Skill — see _lookup_source_action_item).
+
+        Sections:
+          frontmatter (mode, target_skill, source_task_id, generated_at)
+          ## Task name           — from ActionItem.name
+          ## Outcome             — status, created, ended, selected_skills, workflow_id
+          ## Action trace        — every child action+reasoning row from the DB
+          ## Existing SKILL.md   — verbatim, improve mode only
+        """
+        FIELD_CAP = 2048
+        ERROR_CAP = 300
+
+        def truncate(value: Optional[str], cap: int = FIELD_CAP) -> str:
+            if value is None:
+                return "(none)"
+            text = str(value)
+            if len(text) <= cap:
+                return text
+            return text[:cap] + f"\n…[truncated {len(text) - cap} chars]"
+
+        def fmt_ts(ts: Optional[float]) -> str:
+            if not ts:
+                return "(unknown)"
+            try:
+                return datetime.fromtimestamp(ts).isoformat()
+            except Exception:
+                return str(ts)
+
+        child_items = self._gather_child_action_items(source_item.id)
+
+        selected_skills_str = ", ".join(source_item.selected_skills or []) or "(none)"
+        workflow_id_str = source_item.workflow_id or "(none)"
+
+        lines: List[str] = [
+            "---",
+            f"mode: {mode}",
+            f"target_skill: {target_skill}",
+            f"source_task_id: {source_item.id}",
+            f"generated_at: {datetime.utcnow().isoformat()}Z",
+            "---",
+            "",
+            "# Source Task Context",
+            "",
+            "## Task name",
+            truncate(source_item.name),
+            "",
+            "## Outcome",
+            f"- Status: {source_item.status}",
+            f"- Created: {fmt_ts(source_item.created_at)}",
+            f"- Ended: {fmt_ts(source_item.completed_at)}",
+            f"- Selected skills: {selected_skills_str}",
+            f"- Workflow id: {workflow_id_str}",
+            "",
+            "## Action trace",
+            "",
+        ]
+
+        if not child_items:
+            lines.append("(no recorded actions)")
+        else:
+            for idx, item in enumerate(child_items, 1):
+                duration_ms = item.duration
+                duration_str = f"{duration_ms}ms" if duration_ms is not None else "—"
+                lines.append(
+                    f"### [{idx}] {item.name} — {item.status} ({duration_str}) [{item.item_type}]"
+                )
+                lines.append(f"- input: {truncate(item.input_data)}")
+                lines.append(f"- output: {truncate(item.output_data)}")
+                err_text = item.error_message
+                lines.append(
+                    f"- error: {truncate(err_text, ERROR_CAP) if err_text else '(none)'}"
+                )
+                lines.append("")
+
+        if existing_skill_md is not None:
+            lines.append("## Existing SKILL.md")
+            lines.append("")
+            try:
+                existing = existing_skill_md.read_text(encoding="utf-8")
+            except Exception as e:
+                existing = f"(failed to read: {e})"
+            lines.append("```")
+            lines.append(existing)
+            lines.append("```")
+
+        return "\n".join(lines)
+
     # ─────────────────────────────────────────────────────────────────────
     # Scheduler/Proactive Operation Handlers
     # ─────────────────────────────────────────────────────────────────────
@@ -3563,6 +4272,7 @@ async def _handle_model_connection_test(
         provider: str,
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
+        model: Optional[str] = None,
     ) -> None:
         """Test connection to a model provider."""
         try:
@@ -3570,6 +4280,7 @@ async def _handle_model_connection_test(
                 provider=provider,
                 api_key=api_key,
                 base_url=base_url,
+                model=model,
             )
             await self._broadcast({
                 "type": "model_connection_test",
@@ -3623,6 +4334,45 @@ async def _handle_ollama_models_get(self, base_url: Optional[str] = None) -> Non
                 "data": {"success": False, "models": [], "error": str(e)},
             })
 
+    async def _handle_openrouter_models_get(
+        self,
+        base_url: Optional[str] = None,
+        force_refresh: bool = False,
+    ) -> None:
+        """Fetch the OpenRouter model catalog and broadcast it.
+
+        The catalog is public (no auth) and large (~300 entries). The helper
+        caches it in-process for 5 min; pass forceRefresh=True from the UI
+        to bypass the cache.
+        """
+        try:
+            from app.ui_layer.settings.openrouter_catalog import fetch_models
+            result = await asyncio.to_thread(
+                fetch_models, base_url, force_refresh=force_refresh
+            )
+            await self._broadcast({"type": "openrouter_models_get", "data": result})
+        except Exception as e:
+            await self._broadcast({
+                "type": "openrouter_models_get",
+                "data": {"success": False, "models": [], "error": str(e)},
+            })
+
+    async def _handle_openrouter_credits_get(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> None:
+        """Fetch the OpenRouter account credit balance for the configured key."""
+        try:
+            from app.ui_layer.settings.openrouter_catalog import fetch_credits
+            result = await asyncio.to_thread(fetch_credits, api_key, base_url)
+            await self._broadcast({"type": "openrouter_credits_get", "data": result})
+        except Exception as e:
+            await self._broadcast({
+                "type": "openrouter_credits_get",
+                "data": {"success": False, "error": str(e)},
+            })
+
     # ─────────────────────────────────────────────────────────────────────
     # Slow Mode Handlers
     # ─────────────────────────────────────────────────────────────────────
@@ -4308,132 +5058,82 @@ async def _handle_integration_connect_cancel(self, integration_id: str) -> None:
     async def _handle_integration_disconnect(
         self, integration_id: str, account_id: Optional[str] = None
     ) -> None:
-        """Disconnect an integration account."""
-        try:
-            success, message = await disconnect_integration(integration_id, account_id)
-            await self._broadcast({
-                "type": "integration_disconnect_result",
-                "data": {
-                    "success": success,
-                    "message": message,
-                    "id": integration_id,
-                },
-            })
-            # Refresh the list on success
-            if success:
-                await self._handle_integration_list()
-        except Exception as e:
-            await self._broadcast({
-                "type": "integration_disconnect_result",
-                "data": {
-                    "success": False,
-                    "error": str(e),
-                    "id": integration_id,
-                },
-            })
-
-    # =====================
-    # Jira Settings
-    # =====================
+        """Disconnect an integration account.
 
-    async def _handle_jira_get_settings(self) -> None:
-        """Get current Jira watch tag and labels."""
-        try:
-            from app.external_comms.credentials import has_credential, load_credential
-            from app.external_comms.platforms.jira import JiraCredential
-            if not has_credential("jira.json"):
-                await self._broadcast({"type": "jira_settings", "data": {"success": False, "error": "Not connected"}})
-                return
-            cred = load_credential("jira.json", JiraCredential)
-            await self._broadcast({
-                "type": "jira_settings",
-                "data": {
-                    "success": True,
-                    "watch_tag": cred.watch_tag if cred else "",
-                    "watch_labels": cred.watch_labels if cred else [],
-                },
-            })
-        except Exception as e:
-            await self._broadcast({"type": "jira_settings", "data": {"success": False, "error": str(e)}})
+        Heavy teardown (e.g. WhatsApp bridge ``client.destroy()``) can take
+        20+ seconds. We don't want the WS message handler blocked on it —
+        the frontend would show stale "connected" state until the teardown
+        finishes. So we run the disconnect in a background task and let
+        this handler return immediately.
+        """
+        async def _do_disconnect() -> None:
+            try:
+                success, message = await disconnect_integration(integration_id, account_id)
+                await self._broadcast({
+                    "type": "integration_disconnect_result",
+                    "data": {
+                        "success": success,
+                        "message": message,
+                        "id": integration_id,
+                    },
+                })
+                if success:
+                    await self._handle_integration_list()
+            except Exception as e:
+                await self._broadcast({
+                    "type": "integration_disconnect_result",
+                    "data": {
+                        "success": False,
+                        "error": str(e),
+                        "id": integration_id,
+                    },
+                })
 
-    async def _handle_jira_update_settings(self, watch_tag=None, watch_labels=None) -> None:
-        """Update Jira watch tag and/or labels."""
-        try:
-            from app.external_comms.platforms.jira import JiraClient
-            client = JiraClient()
-            if not client.has_credentials():
-                await self._broadcast({"type": "jira_settings_result", "data": {"success": False, "error": "Not connected"}})
-                return
-            if watch_tag is not None:
-                client.set_watch_tag(watch_tag)
-            if watch_labels is not None:
-                if isinstance(watch_labels, str):
-                    watch_labels = [l.strip() for l in watch_labels.split(",") if l.strip()]
-                client.set_watch_labels(watch_labels)
-            # Return updated settings
-            cred = client._load()
-            await self._broadcast({
-                "type": "jira_settings_result",
-                "data": {
-                    "success": True,
-                    "watch_tag": cred.watch_tag,
-                    "watch_labels": cred.watch_labels,
-                    "message": "Jira settings updated",
-                },
-            })
-        except Exception as e:
-            await self._broadcast({"type": "jira_settings_result", "data": {"success": False, "error": str(e)}})
+        asyncio.create_task(_do_disconnect())
 
-    # =====================
-    # GitHub Settings
-    # =====================
+    # ==========================
+    # Generic per-integration config
+    # ==========================
+    # Schema-driven: each integration declares ``config_class`` +
+    # ``config_fields`` on its handler. These two handlers work for
+    # every integration with no per-id branching.
 
-    async def _handle_github_get_settings(self) -> None:
-        """Get current GitHub watch tag and repos."""
+    async def _handle_integration_get_config(self, integration_id: str) -> None:
+        """Send the integration's config schema + current values to the frontend."""
         try:
-            from app.external_comms.credentials import has_credential, load_credential
-            from app.external_comms.platforms.github import GitHubCredential
-            if not has_credential("github.json"):
-                await self._broadcast({"type": "github_settings", "data": {"success": False, "error": "Not connected"}})
+            from craftos_integrations import get_config, get_config_schema, get_metadata
+            meta = get_metadata(integration_id)
+            if meta is None:
+                await self._broadcast({"type": "integration_config", "data": {
+                    "id": integration_id, "success": False, "error": "Unknown integration",
+                }})
                 return
-            cred = load_credential("github.json", GitHubCredential)
-            await self._broadcast({
-                "type": "github_settings",
-                "data": {
-                    "success": True,
-                    "watch_tag": cred.watch_tag if cred else "",
-                    "watch_repos": cred.watch_repos if cred else [],
-                },
-            })
+            await self._broadcast({"type": "integration_config", "data": {
+                "id": integration_id,
+                "success": True,
+                "schema": get_config_schema(integration_id) or [],
+                "values": get_config(integration_id) or {},
+            }})
         except Exception as e:
-            await self._broadcast({"type": "github_settings", "data": {"success": False, "error": str(e)}})
+            await self._broadcast({"type": "integration_config", "data": {
+                "id": integration_id, "success": False, "error": str(e),
+            }})
 
-    async def _handle_github_update_settings(self, watch_tag=None, watch_repos=None) -> None:
-        """Update GitHub watch tag and/or repos."""
+    async def _handle_integration_update_config(self, integration_id: str, values: dict) -> None:
+        """Persist new config values; return the post-write state so the UI can refresh."""
         try:
-            from app.external_comms.platforms.github import GitHubClient
-            client = GitHubClient()
-            if not client.has_credentials():
-                await self._broadcast({"type": "github_settings_result", "data": {"success": False, "error": "Not connected"}})
-                return
-            if watch_tag is not None:
-                client.set_watch_tag(watch_tag)
-            if watch_repos is not None:
-                if isinstance(watch_repos, str):
-                    watch_repos = [r.strip() for r in watch_repos.split(",") if r.strip()]
-                client.set_watch_repos(watch_repos)
-            cred = client._load()
-            await self._broadcast({
-                "type": "github_settings_result",
-                "data": {
-                    "success": True,
-                    "watch_tag": cred.watch_tag,
-                    "watch_repos": cred.watch_repos,
-                    "message": "GitHub settings updated",
-                },
-            })
+            from craftos_integrations import get_config, update_config
+            ok, message = update_config(integration_id, values or {})
+            await self._broadcast({"type": "integration_config_updated", "data": {
+                "id": integration_id,
+                "success": ok,
+                "message": message,
+                "values": get_config(integration_id) if ok else None,
+            }})
         except Exception as e:
-            await self._broadcast({"type": "github_settings_result", "data": {"success": False, "error": str(e)}})
+            await self._broadcast({"type": "integration_config_updated", "data": {
+                "id": integration_id, "success": False, "error": str(e),
+            }})
 
     # ==========================
     # Living UI Settings Handlers
@@ -4445,12 +5145,6 @@ async def _handle_living_ui_settings_get(self) -> None:
         result = get_living_ui_projects()
         await self._broadcast({"type": "living_ui_settings_get", "data": result})
 
-    async def _handle_living_ui_project_action(self, project_id: str, action: str) -> None:
-        """Execute a project action (launch/stop/delete)."""
-        from app.ui_layer.settings.living_ui_settings import living_ui_project_action
-        result = await living_ui_project_action(project_id, action)
-        await self._broadcast({"type": "living_ui_project_action", "data": result})
-
     async def _handle_living_ui_project_setting_update(self, project_id: str, setting: str, value) -> None:
         """Update a per-project setting."""
         from app.ui_layer.settings.living_ui_settings import update_project_setting
@@ -5234,6 +5928,11 @@ async def _handle_action_history(self, before_timestamp: float, limit: int = 15)
                     "input": a.input_data,
                     "output": a.output_data,
                     "error": a.error_message,
+                    "selectedSkills": list(a.selected_skills or []),
+                    "workflowId": a.workflow_id,
+                    "inputTokens": a.input_tokens,
+                    "outputTokens": a.output_tokens,
+                    "cacheTokens": a.cache_tokens,
                 }
                 for a in older_items
             ]
@@ -5819,6 +6518,11 @@ def _get_initial_state(self) -> Dict[str, Any]:
                     "input": a.input_data,
                     "output": a.output_data,
                     "error": a.error_message,
+                    "selectedSkills": list(a.selected_skills or []),
+                    "workflowId": a.workflow_id,
+                    "inputTokens": a.input_tokens,
+                    "outputTokens": a.output_tokens,
+                    "cacheTokens": a.cache_tokens,
                 }
                 for a in self._action_panel.get_items()
             ],
diff --git a/app/ui_layer/adapters/tui_adapter.py b/app/ui_layer/adapters/tui_adapter.py
index 5cd5fd7a..02143d67 100644
--- a/app/ui_layer/adapters/tui_adapter.py
+++ b/app/ui_layer/adapters/tui_adapter.py
@@ -210,12 +210,62 @@ async def update_item_data(
         # TUI doesn't display output/error in the panel
         pass
 
+    async def update_item_tokens(
+        self,
+        item_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        cache_tokens: int,
+    ) -> None:
+        """Update a task item's token counters. No-op for TUI."""
+        # TUI doesn't display per-task token usage in the panel
+        pass
+
     async def clear(self) -> None:
         """Clear all items."""
         self._items.clear()
         self._order.clear()
         await self._adapter.action_updates.put(ActionPanelUpdate("clear", None))
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks remain visible.
+
+        Returns:
+            Number of tasks removed (does not count child actions).
+        """
+        terminal_statuses = {"completed", "error", "cancelled"}
+
+        terminal_task_ids = {
+            item_id
+            for item_id, item in self._items.items()
+            if item.item_type == "task" and item.status in terminal_statuses
+        }
+
+        if not terminal_task_ids:
+            return 0
+
+        removed_ids = [
+            item_id
+            for item_id, item in list(self._items.items())
+            if item_id in terminal_task_ids or item.task_id in terminal_task_ids
+        ]
+
+        for item_id in removed_ids:
+            self._items.pop(item_id, None)
+        self._order = [iid for iid in self._order if iid not in removed_ids]
+
+        for item_id in removed_ids:
+            await self._adapter.action_updates.put(
+                ActionPanelUpdate(
+                    "remove",
+                    TUIActionItem(id=item_id, display_name="", item_type="", status=""),
+                )
+            )
+
+        return len(terminal_task_ids)
+
     def select_task(self, task_id: Optional[str]) -> None:
         """Select a task for detail view."""
         self._adapter._selected_task_id = task_id
diff --git a/app/ui_layer/browser/frontend/package-lock.json b/app/ui_layer/browser/frontend/package-lock.json
index b1650464..9ae468d7 100644
--- a/app/ui_layer/browser/frontend/package-lock.json
+++ b/app/ui_layer/browser/frontend/package-lock.json
@@ -61,7 +61,6 @@
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -1451,14 +1450,15 @@
       "version": "15.7.15",
       "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
       "integrity": "sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/@types/react": {
       "version": "18.3.28",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-18.3.28.tgz",
       "integrity": "sha512-z9VXpC7MWrhfWipitjNdgCauoMLRdIILQsAEV+ZesIzBq/oUlxk0m3ApZuMFCXdnS4U7KrI+l3WRUEGQ8K1QKw==",
+      "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/prop-types": "*",
         "csstype": "^3.2.2"
@@ -1520,7 +1520,6 @@
       "integrity": "sha512-4Z+L8I2OqhZV8qA132M4wNL30ypZGYOQVBfMgxDH/K5UX0PNqTu1c6za9ST5r9+tavvHiTWmBnKzpCJ/GlVFtg==",
       "dev": true,
       "license": "BSD-2-Clause",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "7.18.0",
         "@typescript-eslint/types": "7.18.0",
@@ -1707,7 +1706,6 @@
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -1858,7 +1856,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -2034,6 +2031,7 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/debug": {
@@ -2197,7 +2195,6 @@
       "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.2.0",
         "@eslint-community/regexpp": "^4.6.1",
@@ -4239,7 +4236,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-18.3.1.tgz",
       "integrity": "sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0"
       },
@@ -4252,7 +4248,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
       "integrity": "sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "loose-envify": "^1.1.0",
         "scheduler": "^0.23.2"
@@ -4749,7 +4744,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -4920,7 +4914,6 @@
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
index ea188fd2..09c04973 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.module.css
@@ -7,6 +7,16 @@
   min-width: 0;
 }
 
+/* Wraps the scrolling list so the scroll-to-bottom button can sit absolutely
+   over the chat without scrolling along with the messages. */
+.messagesArea {
+  position: relative;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
 .messagesContainer {
   flex: 1;
   overflow-y: auto;
@@ -16,6 +26,72 @@
   gap: var(--space-3);
 }
 
+/* Slack-style date divider: a thin rule with a centered pill label */
+.dateDivider {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-2) 0 var(--space-3);
+  user-select: none;
+}
+
+.dateDividerLine {
+  flex: 1;
+  height: 1px;
+  background: var(--border-primary);
+}
+
+.dateDividerLabel {
+  flex-shrink: 0;
+  padding: 2px 12px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 999px;
+  font-size: var(--text-xs);
+  font-weight: var(--font-semibold);
+  color: var(--text-secondary);
+  letter-spacing: 0.01em;
+}
+
+/* Floating scroll-to-bottom affordance. Appears when the user has scrolled
+   away from the latest message; click to jump back to the bottom. */
+.scrollToBottomBtn {
+  position: absolute;
+  right: var(--space-4);
+  bottom: var(--space-3);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: 999px;
+  color: var(--text-secondary);
+  cursor: pointer;
+  opacity: 0.85;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+  transition: opacity var(--transition-fast), background var(--transition-fast),
+    color var(--transition-fast), transform var(--transition-fast);
+  z-index: 5;
+  animation: scrollBtnFadeIn 120ms ease-out;
+}
+
+.scrollToBottomBtn:hover {
+  opacity: 1;
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.scrollToBottomBtn:active {
+  transform: translateY(1px);
+}
+
+@keyframes scrollBtnFadeIn {
+  from { opacity: 0; transform: translateY(4px); }
+  to   { opacity: 0.85; transform: translateY(0); }
+}
+
 .emptyState {
   flex: 1;
   display: flex;
@@ -271,31 +347,87 @@
   box-shadow: 0 0 0 2px var(--color-primary-subtle);
 }
 
-/* Mic button + language selector grouped together */
+/* Mic + language selector */
 .micGroup {
   display: flex;
   align-items: center;
-  gap: 2px;
   position: relative;
+  gap: 0;
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-lg);
 }
 
-.langBtn {
+.micCombo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
   background: transparent;
   border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  padding: 6px;
+  border-radius: var(--radius-lg) 0 0 var(--radius-lg);
+  outline: none;
+  transition: color 0.15s, background 0.15s;
+}
+
+.micCombo:hover {
   color: var(--text-primary);
+  background: var(--bg-tertiary);
+}
+
+.micCombo.micComboActive {
+  color: var(--color-error, #ef4444);
+}
+
+.micIconWrap {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+}
+
+/* Pulsing ring around mic icon when recording */
+.micPulseRing {
+  position: absolute;
+  inset: -3px;
+  border-radius: 50%;
+  border: 2px solid var(--color-error, #ef4444);
+  animation: micRingPulse 1.4s ease-in-out infinite;
+  pointer-events: none;
+}
+
+@keyframes micRingPulse {
+  0%, 100% { transform: scale(1); opacity: 0.8; }
+  50% { transform: scale(1.25); opacity: 0; }
+}
+
+.langBtn {
+  display: flex;
+  align-items: center;
+  align-self: stretch;
+  background: transparent;
+  border: none;
+  border-left: 1px solid var(--border-primary);
+  color: var(--text-secondary);
   font-size: 10px;
   font-family: inherit;
   font-weight: 600;
   cursor: pointer;
-  padding: 2px 3px;
-  border-radius: var(--radius-sm);
+  padding: 0 8px;
+  border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
   line-height: 1;
   outline: none;
   white-space: nowrap;
+  transition: color 0.15s, background 0.15s;
 }
 
 .langBtn:hover:not(:disabled) {
   background: var(--bg-tertiary);
+  color: var(--text-primary);
 }
 
 .langBtn:disabled {
@@ -303,6 +435,10 @@
   cursor: not-allowed;
 }
 
+.langBtn.langBtnActive {
+  color: var(--color-error, #ef4444);
+}
+
 .langDropdown {
   position: absolute;
   bottom: calc(100% + 6px);
@@ -352,42 +488,6 @@
   opacity: 0.8;
 }
 
-/* 3 bouncing dots shown while listening */
-.listeningDots {
-  display: flex;
-  align-items: center;
-  gap: 4px;
-  padding: 4px var(--space-3) 0;
-}
-
-.listeningDots span {
-  display: block;
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  background: var(--color-primary);
-  animation: dotBounce 1.2s ease-in-out infinite;
-}
-
-.listeningDots span:nth-child(1) { animation-delay: 0s; }
-.listeningDots span:nth-child(2) { animation-delay: 0.2s; }
-.listeningDots span:nth-child(3) { animation-delay: 0.4s; }
-
-@keyframes dotBounce {
-  0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
-  30% { transform: translateY(-5px); opacity: 1; }
-}
-
-/* Mic button pulse animation when recording */
-.micListening {
-  animation: micPulse 1.2s ease-in-out infinite;
-}
-
-@keyframes micPulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.4; }
-}
-
 /* Attachment preview modal */
 .previewOverlay {
   position: fixed;
diff --git a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
index 7dc810ab..14ea658d 100644
--- a/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
+++ b/app/ui_layer/browser/frontend/src/components/Chat/Chat.tsx
@@ -1,6 +1,6 @@
 import React, { useState, useRef, useEffect, useLayoutEffect, KeyboardEvent, useCallback, ChangeEvent, useMemo } from 'react'
 import ReactDOM from 'react-dom'
-import { Send, Paperclip, X, Loader2, File, AlertCircle, Reply, Mic, MicOff } from 'lucide-react'
+import { Send, Paperclip, X, Loader2, File, AlertCircle, Reply, Mic, MicOff, ChevronDown } from 'lucide-react'
 import { useVirtualizer } from '@tanstack/react-virtual'
 import { useWebSocket } from '../../contexts/WebSocketContext'
 import { useToast } from '../../contexts/ToastContext'
@@ -54,12 +54,48 @@ const formatFileSize = (bytes: number): string => {
   return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i]
 }
 
+// Stable per-day key (local time) for grouping consecutive messages by date.
+const getDateKey = (timestamp: number): string => {
+  const d = new Date(timestamp * 1000)
+  return `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`
+}
+
+// Slack-style date divider label: "Today", "Yesterday", weekday for the
+// last week, otherwise a full localized date.
+const formatDateDivider = (timestamp: number): string => {
+  const date = new Date(timestamp * 1000)
+  const now = new Date()
+  const sameDay = (a: Date, b: Date) =>
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+
+  if (sameDay(date, now)) return 'Today'
+  const yesterday = new Date(now)
+  yesterday.setDate(yesterday.getDate() - 1)
+  if (sameDay(date, yesterday)) return 'Yesterday'
+
+  const msPerDay = 1000 * 60 * 60 * 24
+  const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  const startOfDate = new Date(date.getFullYear(), date.getMonth(), date.getDate())
+  const daysDiff = Math.round((startOfToday.getTime() - startOfDate.getTime()) / msPerDay)
+
+  if (daysDiff > 0 && daysDiff < 7) {
+    return date.toLocaleDateString(undefined, { weekday: 'long', month: 'long', day: 'numeric' })
+  }
+  if (date.getFullYear() === now.getFullYear()) {
+    return date.toLocaleDateString(undefined, { weekday: 'long', month: 'long', day: 'numeric' })
+  }
+  return date.toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })
+}
+
 export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const {
     messages,
     actions,
     connected,
     sendMessage,
+    sendCommand,
     sendOptionClick,
     openFile,
     openFolder,
@@ -112,6 +148,8 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
   const wasNearBottomRef = useRef(true)
   const prevMessageCountRef = useRef(0)
   const hasInitialScrolled = useRef(false)
+  const prevScrollTopRef = useRef(0)
+  const [showScrollToBottom, setShowScrollToBottom] = useState(false)
 
   const attachmentValidation = useMemo(() => {
     const totalSize = pendingAttachments.reduce((sum, att) => sum + att.size, 0)
@@ -140,12 +178,6 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
     return lastSeenIdx + 1
   }, [orderedMessages, lastSeenMessageId])
 
-  const isNearBottom = useCallback(() => {
-    const container = parentRef.current
-    if (!container) return true
-    return container.scrollHeight - container.scrollTop - container.clientHeight < 100
-  }, [])
-
   // Close language dropdown when clicking outside
   useEffect(() => {
     if (!langOpen) return
@@ -166,19 +198,45 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
     return () => document.removeEventListener('keydown', handler)
   }, [previewAttachment])
 
-  // Track scroll position + load older messages on scroll-to-top
+  // Track scroll position + direction, and load older messages on scroll-to-top.
+  // The scroll-to-bottom button surfaces when the user is scrolling *toward*
+  // the bottom but hasn't arrived yet — scrolling up to read history hides it.
   useEffect(() => {
     const container = parentRef.current
     if (!container) return
+    prevScrollTopRef.current = container.scrollTop
     const handleScroll = () => {
-      wasNearBottomRef.current = isNearBottom()
-      if (container.scrollTop < 100 && hasMoreMessages && !loadingOlderMessages) {
+      const scrollTop = container.scrollTop
+      const distFromBottom = container.scrollHeight - scrollTop - container.clientHeight
+      const nearBottom = distFromBottom < 100
+      wasNearBottomRef.current = nearBottom
+
+      const delta = scrollTop - prevScrollTopRef.current
+      prevScrollTopRef.current = scrollTop
+
+      if (nearBottom) {
+        setShowScrollToBottom(false)
+      } else if (delta > 0) {
+        // Scrolling down (toward latest) — offer a quick jump.
+        setShowScrollToBottom(true)
+      } else if (delta < 0) {
+        // Scrolling up (reading history) — get out of the way.
+        setShowScrollToBottom(false)
+      }
+
+      if (scrollTop < 100 && hasMoreMessages && !loadingOlderMessages) {
         loadOlderMessages()
       }
     }
     container.addEventListener('scroll', handleScroll)
     return () => container.removeEventListener('scroll', handleScroll)
-  }, [isNearBottom, hasMoreMessages, loadingOlderMessages, loadOlderMessages])
+  }, [hasMoreMessages, loadingOlderMessages, loadOlderMessages])
+
+  const scrollToBottom = useCallback(() => {
+    if (orderedMessages.length === 0) return
+    virtualizer.scrollToIndex(orderedMessages.length - 1, { align: 'end', behavior: 'smooth' })
+    setShowScrollToBottom(false)
+  }, [virtualizer, orderedMessages.length])
 
   // Scroll to unread on mount, auto-scroll on new messages if near bottom
   useEffect(() => {
@@ -313,12 +371,24 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
         setIsListening(false)
       }
 
-      sendMessage(
-        input.trim(),
-        pendingAttachments.length > 0 ? pendingAttachments : undefined,
-        replyContext,
-        livingUIId
-      )
+      const trimmed = input.trim()
+      // Slash commands route through the dedicated command channel so no
+      // optimistic user bubble is inserted — the backend's CommandExecutor
+      // responds with system/error messages rather than echoing user input.
+      // Attachments + slash command falls through to chat (commands don't
+      // accept attachments), which preserves the existing behavior for that
+      // edge case.
+      const isSlashCommand = trimmed.startsWith('/') && pendingAttachments.length === 0
+      if (isSlashCommand) {
+        sendCommand(trimmed)
+      } else {
+        sendMessage(
+          trimmed,
+          pendingAttachments.length > 0 ? pendingAttachments : undefined,
+          replyContext,
+          livingUIId
+        )
+      }
       if (!connected) {
         showToast('info', 'Reconnecting — your message will send when the connection is restored.')
       }
@@ -473,64 +543,86 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
 
   return (
     <div className={styles.chat}>
-      <div className={styles.messagesContainer} ref={parentRef}>
-        {orderedMessages.length === 0 ? (
-          <div className={styles.emptyState}>
-            <div className={styles.emptyIcon}>
-              <svg width="48" height="48" viewBox="0 0 32 32" fill="none">
-                <rect width="32" height="32" rx="6" fill="var(--color-primary-light)"/>
-                <path d="M8 12h16M8 16h12M8 20h8" stroke="var(--color-primary)" strokeWidth="2" strokeLinecap="round"/>
-              </svg>
-            </div>
-            <h3>{emptyMessage || 'Start a conversation'}</h3>
-            <p>{livingUIId ? 'Ask the agent about this UI' : 'Send a message to begin interacting with CraftBot'}</p>
-          </div>
-        ) : (
-          <div
-            style={{
-              height: `${virtualizer.getTotalSize()}px`,
-              width: '100%',
-              position: 'relative',
-            }}
-          >
-            {loadingOlderMessages && (
-              <div style={{ textAlign: 'center', padding: '8px 0', color: 'var(--text-tertiary)', fontSize: 'var(--text-xs)' }}>
-                <Loader2 size={14} style={{ display: 'inline', animation: 'spin 1s linear infinite' }} /> Loading older messages...
+      <div className={styles.messagesArea}>
+        <div className={styles.messagesContainer} ref={parentRef}>
+          {orderedMessages.length === 0 ? (
+            <div className={styles.emptyState}>
+              <div className={styles.emptyIcon}>
+                <svg width="48" height="48" viewBox="0 0 32 32" fill="none">
+                  <rect width="32" height="32" rx="6" fill="var(--color-primary-light)"/>
+                  <path d="M8 12h16M8 16h12M8 20h8" stroke="var(--color-primary)" strokeWidth="2" strokeLinecap="round"/>
+                </svg>
               </div>
-            )}
-            {virtualizer.getVirtualItems().map((virtualItem) => {
-              const message = orderedMessages[virtualItem.index]
-              // Prefer clientId as the React key so that when a pending optimistic
-              // message is reconciled with the server echo (messageId changes from
-              // `pending:<cid>` to the real id), React reuses the same DOM node —
-              // letting the CSS transform transition animate the slide into
-              // its server-canonical sorted position.
-              const rowKey = message.clientId || message.messageId || virtualItem.index
-              return (
-                <div
-                  key={rowKey}
-                  data-index={virtualItem.index}
-                  ref={virtualizer.measureElement}
-                  style={{
-                    position: 'absolute',
-                    top: 0,
-                    left: 0,
-                    width: '100%',
-                    transform: `translateY(${virtualItem.start}px)`,
-                    transition: 'transform 250ms ease',
-                  }}
-                >
-                  <ChatMessageItem
-                    message={message}
-                    onOpenFile={openFile}
-                    onOpenFolder={openFolder}
-                    onReply={handleChatReply}
-                    onOptionClick={sendOptionClick}
-                  />
+              <h3>{emptyMessage || 'Start a conversation'}</h3>
+              <p>{livingUIId ? 'Ask the agent about this UI' : 'Send a message to begin interacting with CraftBot'}</p>
+            </div>
+          ) : (
+            <div
+              style={{
+                height: `${virtualizer.getTotalSize()}px`,
+                width: '100%',
+                position: 'relative',
+              }}
+            >
+              {loadingOlderMessages && (
+                <div style={{ textAlign: 'center', padding: '8px 0', color: 'var(--text-tertiary)', fontSize: 'var(--text-xs)' }}>
+                  <Loader2 size={14} style={{ display: 'inline', animation: 'spin 1s linear infinite' }} /> Loading older messages...
                 </div>
-              )
-            })}
-          </div>
+              )}
+              {virtualizer.getVirtualItems().map((virtualItem) => {
+                const message = orderedMessages[virtualItem.index]
+                const prev = virtualItem.index > 0 ? orderedMessages[virtualItem.index - 1] : null
+                const showDateDivider = !prev || getDateKey(prev.timestamp) !== getDateKey(message.timestamp)
+                // Prefer clientId as the React key so that when a pending optimistic
+                // message is reconciled with the server echo (messageId changes from
+                // `pending:<cid>` to the real id), React reuses the same DOM node —
+                // letting the CSS transform transition animate the slide into
+                // its server-canonical sorted position.
+                const rowKey = message.clientId || message.messageId || virtualItem.index
+                return (
+                  <div
+                    key={rowKey}
+                    data-index={virtualItem.index}
+                    ref={virtualizer.measureElement}
+                    style={{
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      width: '100%',
+                      transform: `translateY(${virtualItem.start}px)`,
+                      transition: 'transform 250ms ease',
+                    }}
+                  >
+                    {showDateDivider && (
+                      <div className={styles.dateDivider} role="separator" aria-label={formatDateDivider(message.timestamp)}>
+                        <span className={styles.dateDividerLine} />
+                        <span className={styles.dateDividerLabel}>{formatDateDivider(message.timestamp)}</span>
+                        <span className={styles.dateDividerLine} />
+                      </div>
+                    )}
+                    <ChatMessageItem
+                      message={message}
+                      onOpenFile={openFile}
+                      onOpenFolder={openFolder}
+                      onReply={handleChatReply}
+                      onOptionClick={sendOptionClick}
+                    />
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+        {showScrollToBottom && orderedMessages.length > 0 && (
+          <button
+            type="button"
+            className={styles.scrollToBottomBtn}
+            onClick={scrollToBottom}
+            aria-label="Scroll to latest message"
+            title="Scroll to latest message"
+          >
+            <ChevronDown size={18} />
+          </button>
         )}
       </div>
 
@@ -546,16 +638,19 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
         <IconButton icon={<Paperclip size={18} />} variant="ghost" tooltip="Attach file" onClick={handleAttachClick} />
 
         <div className={styles.micGroup} ref={langDropdownRef}>
-          <IconButton
-            icon={isListening ? <MicOff size={18} /> : <Mic size={18} />}
-            variant="ghost"
-            active={isListening}
-            tooltip={isListening ? 'Stop listening' : 'Voice input'}
+          <button
+            type="button"
+            className={`${styles.micCombo}${isListening ? ` ${styles.micComboActive}` : ''}`}
+            title={isListening ? 'Stop listening' : 'Voice input'}
             onClick={toggleListening}
-            className={isListening ? styles.micListening : undefined}
-          />
+          >
+            <span className={styles.micIconWrap}>
+              {isListening ? <MicOff size={18} /> : <Mic size={18} />}
+              {isListening && <span className={styles.micPulseRing} />}
+            </span>
+          </button>
           <button
-            className={styles.langBtn}
+            className={`${styles.langBtn}${isListening ? ` ${styles.langBtnActive}` : ''}`}
             onClick={() => !isListening && setLangOpen(o => !o)}
             title="Speech language"
             disabled={isListening}
@@ -633,12 +728,6 @@ export function Chat({ livingUIId, placeholder, emptyMessage }: ChatProps) {
             </div>
           )}
 
-          {isListening && (
-            <div className={styles.listeningDots}>
-              <span /><span /><span />
-            </div>
-          )}
-
           <textarea
             ref={inputRef}
             className={`${styles.input}${isListening ? ` ${styles.inputListening}` : ''}`}
diff --git a/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.module.css b/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.module.css
index 5385702a..544838e7 100644
--- a/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.module.css
+++ b/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.module.css
@@ -1,4 +1,4 @@
-/* Create Living UI Modal */
+/* Create Living UI Modal — full-screen marketplace overlay */
 .modalOverlay {
   position: fixed;
   top: 0;
@@ -15,21 +15,18 @@
 }
 
 @keyframes fadeIn {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
+  from { opacity: 0; }
+  to { opacity: 1; }
 }
 
 .modalContent {
   background: var(--bg-secondary);
   border: 1px solid var(--border-primary);
   border-radius: var(--radius-lg);
-  width: 100%;
-  max-width: 520px;
-  max-height: 90vh;
+  width: 95vw;
+  max-width: 1400px;
+  height: 95vh;
+  max-height: 95vh;
   overflow: hidden;
   display: flex;
   flex-direction: column;
@@ -37,14 +34,8 @@
 }
 
 @keyframes slideUp {
-  from {
-    opacity: 0;
-    transform: translateY(10px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
+  from { opacity: 0; transform: translateY(10px); }
+  to { opacity: 1; transform: translateY(0); }
 }
 
 .modalHeader {
@@ -53,6 +44,7 @@
   justify-content: space-between;
   padding: var(--space-4);
   border-bottom: 1px solid var(--border-primary);
+  flex-shrink: 0;
 }
 
 .headerTitle {
@@ -91,14 +83,335 @@
   color: var(--text-primary);
 }
 
-.modalBody {
+/* Tabs */
+.tabs {
+  display: flex;
+  border-bottom: 1px solid var(--border-primary);
+  padding: 0 var(--space-4);
+  flex-shrink: 0;
+}
+
+.tab {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-3) var(--space-4);
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-weight: var(--font-normal);
+  font-size: var(--text-sm);
+  font-family: inherit;
+  transition: color var(--transition-fast), border-color var(--transition-fast);
+}
+
+.tab:hover {
+  color: var(--text-primary);
+}
+
+.tabActive {
+  color: var(--text-primary);
+  border-bottom-color: var(--color-primary);
+  font-weight: var(--font-semibold);
+}
+
+/* Marketplace surface */
+.marketplaceBody {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+
+.toolbar {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+  padding: var(--space-4) var(--space-4) var(--space-3);
+  border-bottom: 1px solid var(--border-primary);
+  flex-shrink: 0;
+}
+
+.searchWrapper {
+  position: relative;
+  max-width: 480px;
+}
+
+.searchIcon {
+  position: absolute;
+  left: var(--space-3);
+  top: 50%;
+  transform: translateY(-50%);
+  color: var(--text-muted);
+  pointer-events: none;
+}
+
+.searchInput {
+  width: 100%;
+  padding: var(--space-2) var(--space-3) var(--space-2) calc(var(--space-3) + 20px);
+  font-size: var(--text-sm);
+  font-family: inherit;
+  color: var(--text-primary);
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  transition: border-color var(--transition-fast);
+}
+
+.searchInput:focus {
+  outline: none;
+  border-color: var(--color-primary);
+}
+
+.tagsRow {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+  align-items: center;
+}
+
+.tagsLabel {
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+  margin-right: var(--space-1);
+}
+
+.tagChip {
+  padding: 4px 10px;
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: 999px;
+  color: var(--text-muted);
+  font-size: var(--text-xs);
+  font-family: inherit;
+  cursor: pointer;
+  transition: all var(--transition-fast);
+  white-space: nowrap;
+}
+
+.tagChip:hover {
+  border-color: var(--color-primary);
+  color: var(--text-primary);
+}
+
+.tagChipActive {
+  background: var(--color-primary);
+  border-color: var(--color-primary);
+  color: white;
+}
+
+.tagChipActive:hover {
+  color: white;
+}
+
+.marketplaceContent {
+  flex: 1;
+  overflow-y: auto;
   padding: var(--space-4);
+}
+
+.appsGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: var(--space-4);
+}
+
+.appCard {
+  display: flex;
+  flex-direction: column;
+  background: var(--bg-tertiary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+  transition: border-color var(--transition-fast), transform var(--transition-fast);
+}
+
+.appCard:hover {
+  border-color: var(--color-primary);
+  transform: translateY(-2px);
+}
+
+.appCardThumb {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  background: var(--bg-secondary);
+  display: block;
+}
+
+.appCardPlaceholder {
+  width: 100%;
+  aspect-ratio: 16 / 9;
+  background: var(--bg-secondary);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.appCardPlaceholderIcon {
+  color: var(--text-muted);
+  opacity: 0.5;
+}
+
+.appCardBody {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  padding: var(--space-3);
+  flex: 1;
+}
+
+.appCardHeader {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--space-2);
+}
+
+.appCardName {
+  font-weight: var(--font-semibold);
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+}
+
+.appCardVersion {
+  font-size: 10px;
+  color: var(--text-muted);
+  flex-shrink: 0;
+}
+
+.appCardTags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.tag {
+  font-size: 10px;
+  padding: 1px 6px;
+  background: var(--bg-secondary);
+  border-radius: var(--radius-sm);
+  color: var(--text-muted);
+}
+
+.appCardDesc {
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+  line-height: 1.5;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.appCardFooter {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+  padding: var(--space-3);
+  border-top: 1px solid var(--border-primary);
+  background: var(--bg-secondary);
+}
+
+.installedBadge {
+  font-size: 10px;
+  color: var(--color-success, #22c55e);
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  white-space: nowrap;
+}
+
+/* Empty / loading / error states */
+.stateCenter {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  padding: var(--space-6);
+  color: var(--text-muted);
+  min-height: 240px;
+}
+
+.stateIcon {
+  margin-bottom: var(--space-3);
+  opacity: 0.5;
+}
+
+.stateText {
+  margin: 0 0 var(--space-3);
+  font-size: var(--text-sm);
+}
+
+.spinner {
+  animation: spin 1s linear infinite;
+}
+
+/* Configure-app panel (when customizable fields exist) */
+.configBody {
+  flex: 1;
   overflow-y: auto;
+  padding: var(--space-4);
+  display: flex;
+  flex-direction: column;
+}
+
+.configCard {
+  background: var(--bg-tertiary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  padding: var(--space-4);
+  width: 100%;
+  max-width: 560px;
+  margin: 0 auto;
+}
+
+.configHeader {
+  margin-bottom: var(--space-4);
+}
+
+.configHeader h4 {
+  font-size: var(--text-base);
+  font-weight: var(--font-semibold);
+  color: var(--text-primary);
+  margin: 0 0 var(--space-1);
+}
+
+.configHeader p {
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+  margin: 0;
+}
+
+.configActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--space-2);
+  margin-top: var(--space-4);
+}
+
+/* Centered form wrapper (used by Custom + Import + Configure tabs) */
+.centeredForm {
+  width: 100%;
+  max-width: 720px;
+  margin: 0 auto;
   display: flex;
   flex-direction: column;
   gap: var(--space-4);
 }
 
+/* Scrollable body for form-based tabs */
+.modalBody {
+  padding: var(--space-4);
+  overflow-y: auto;
+  flex: 1;
+  min-height: 0;
+}
+
 .formGroup {
   display: flex;
   flex-direction: column;
@@ -154,7 +467,7 @@
   border-radius: var(--radius-md);
   transition: border-color var(--transition-fast);
   resize: vertical;
-  min-height: 200px;
+  min-height: 240px;
 }
 
 .textareaLarge:focus {
@@ -196,12 +509,79 @@
   gap: var(--space-2);
   padding: var(--space-4);
   border-top: 1px solid var(--border-primary);
+  flex-shrink: 0;
+}
+
+/* Import tab divider + drop zone */
+.orDivider {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  color: var(--text-muted);
+  font-size: var(--text-xs);
+}
+
+.orDivider::before,
+.orDivider::after {
+  content: '';
+  flex: 1;
+  height: 1px;
+  background: var(--border-primary);
+}
+
+.dropZone {
+  border: 2px dashed var(--border-primary);
+  border-radius: var(--radius-lg);
+  padding: var(--space-6) var(--space-4);
+  text-align: center;
+  cursor: pointer;
+  transition: border-color var(--transition-fast), background var(--transition-fast);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+.dropZone:hover {
+  border-color: var(--color-primary);
+  background: var(--bg-tertiary);
 }
 
-/* Responsive adjustments */
-@media (max-width: 480px) {
+.dropZoneDragOver {
+  border-color: var(--color-primary);
+  background: var(--bg-tertiary);
+}
+
+.dropZoneIcon {
+  color: var(--text-muted);
+}
+
+.dropZoneLabel {
+  margin: 0;
+  font-size: var(--text-sm);
+  font-weight: var(--font-medium);
+  color: var(--text-primary);
+}
+
+.dropZoneSub {
+  margin: 0;
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+  .modalOverlay {
+    padding: 0;
+  }
   .modalContent {
-    max-width: 100%;
-    margin: var(--space-2);
+    width: 100vw;
+    height: 100vh;
+    max-height: 100vh;
+    border-radius: 0;
+    border: none;
+  }
+  .appsGrid {
+    grid-template-columns: 1fr;
   }
 }
diff --git a/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.tsx b/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.tsx
index 06636cf8..233b0bb9 100644
--- a/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.tsx
+++ b/app/ui_layer/browser/frontend/src/components/ui/CreateLivingUIModal.tsx
@@ -1,5 +1,5 @@
 import React, { useState, useEffect, useRef, useMemo, useCallback } from 'react'
-import { X, Sparkles, Download, Loader2, Package, FolderInput, Upload, Check } from 'lucide-react'
+import { X, Sparkles, Download, Loader2, Package, FolderInput, Upload, Check, Search } from 'lucide-react'
 import { Button } from './Button'
 import { useSettingsWebSocket } from '../../pages/Settings/useSettingsWebSocket'
 import type { LivingUICreateRequest } from '../../types'
@@ -48,9 +48,35 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
   // Import tab state
   const [importSource, setImportSource] = useState('')
   const [importing, setImporting] = useState(false)
+  const [dropActive, setDropActive] = useState(false)
 
   // Marketplace state
   const { send, onMessage, isConnected } = useSettingsWebSocket()
+  const [apps, setApps] = useState<MarketplaceApp[]>([])
+  const [marketplaceLoading, setMarketplaceLoading] = useState(false)
+  const [marketplaceError, setMarketplaceError] = useState<string | null>(null)
+  const [installingIds, setInstallingIds] = useState<Set<string>>(new Set())
+  const [installCounts, setInstallCounts] = useState<Map<string, number>>(new Map())
+  const [configuringApp, setConfiguringApp] = useState<MarketplaceApp | null>(null)
+  const installTimeoutsRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map())
+  const [customValues, setCustomValues] = useState<Record<string, string>>({})
+
+  // Marketplace filter state
+  const [searchQuery, setSearchQuery] = useState('')
+  const [selectedTags, setSelectedTags] = useState<Set<string>>(new Set())
+  const [thumbFailures, setThumbFailures] = useState<Set<string>>(new Set())
+  const [tagsExpanded, setTagsExpanded] = useState(false)
+
+  const nameInputRef = useRef<HTMLInputElement>(null)
+  const wordCount = useMemo(() => countWords(description), [description])
+
+  const onCloseRef = useRef(onClose)
+  const onInstalledRef = useRef(onInstalled)
+  useEffect(() => { onCloseRef.current = onClose }, [onClose])
+  useEffect(() => { onInstalledRef.current = onInstalled }, [onInstalled])
+  useEffect(() => () => { installTimeoutsRef.current.forEach(t => clearTimeout(t)) }, [])
+  // Accumulate projectIds from completed installs — navigate only when all installs finish
+  const pendingNavigationsRef = useRef<string[]>([])
 
   // Upload ZIP → stage on server → send to agent via WebSocket
   const handleZipUpload = async (file: File) => {
@@ -63,7 +89,6 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
       const resp = await fetch('/api/living-ui/import', { method: 'POST', body: formData })
       const result = await resp.json()
       if (result.success && result.path) {
-        // File staged — send to agent flow
         send('living_ui_import', { source: result.path, name: result.name || zipName })
         onClose()
       } else {
@@ -75,25 +100,6 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
       setImporting(false)
     }
   }
-  const [apps, setApps] = useState<MarketplaceApp[]>([])
-  const [marketplaceLoading, setMarketplaceLoading] = useState(false)
-  const [marketplaceError, setMarketplaceError] = useState<string | null>(null)
-  const [installingIds, setInstallingIds] = useState<Set<string>>(new Set())
-  const [installCounts, setInstallCounts] = useState<Map<string, number>>(new Map())
-  const [configuringApp, setConfiguringApp] = useState<MarketplaceApp | null>(null)
-  const installTimeoutsRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map())
-  const [customValues, setCustomValues] = useState<Record<string, string>>({})
-
-  const nameInputRef = useRef<HTMLInputElement>(null)
-  const wordCount = useMemo(() => countWords(description), [description])
-
-  const onCloseRef = useRef(onClose)
-  const onInstalledRef = useRef(onInstalled)
-  useEffect(() => { onCloseRef.current = onClose }, [onClose])
-  useEffect(() => { onInstalledRef.current = onInstalled }, [onInstalled])
-  useEffect(() => () => { installTimeoutsRef.current.forEach(t => clearTimeout(t)) }, [])
-  // Accumulate projectIds from completed installs — navigate only when all installs finish
-  const pendingNavigationsRef = useRef<string[]>([])
 
   // Reset form fields on open — intentionally NOT resetting installingIds/completedIds
   // so ongoing installs remain visible when user closes and reopens the modal
@@ -104,7 +110,8 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
       setErrors({})
       setConfiguringApp(null)
       setCustomValues({})
-      // Fetch marketplace if on that tab
+      setSearchQuery('')
+      setSelectedTags(new Set())
       if (activeTab === 'marketplace' && apps.length === 0) {
         fetchMarketplace()
       }
@@ -144,7 +151,6 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
         console.log('[CreateLivingUIModal] received living_ui_marketplace_install:', data)
         const finishedId = data.appId as string | undefined
         if (data.status === 'success') {
-          // Queue navigation — don't interrupt the user until all installs are done
           const projectId = data.project?.id
           if (projectId) pendingNavigationsRef.current.push(projectId)
 
@@ -163,7 +169,6 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
             if (finishedId) next.delete(finishedId)
             else next.clear()
             if (next.size === 0) {
-              // All done — navigate to the last completed project then close
               const lastProjectId = pendingNavigationsRef.current.at(-1)
               pendingNavigationsRef.current = []
               if (lastProjectId && onInstalledRef.current) {
@@ -196,15 +201,50 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
     send('living_ui_marketplace_list')
   }, [send])
 
+  // Derive tag list from catalogue, sorted by frequency (popular first)
+  const allTags = useMemo(() => {
+    const counts = new Map<string, number>()
+    apps.forEach(a => a.tags?.forEach(t => counts.set(t, (counts.get(t) || 0) + 1)))
+    return Array.from(counts.entries())
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([t]) => t)
+  }, [apps])
+
+  const TAG_COLLAPSE_LIMIT = 6
+  const visibleTags = tagsExpanded ? allTags : allTags.slice(0, TAG_COLLAPSE_LIMIT)
+  const hiddenTagCount = Math.max(0, allTags.length - TAG_COLLAPSE_LIMIT)
+
+  const filteredApps = useMemo(() => {
+    const q = searchQuery.trim().toLowerCase()
+    return apps.filter(app => {
+      if (q) {
+        const hay = `${app.name} ${app.description} ${(app.tags || []).join(' ')}`.toLowerCase()
+        if (!hay.includes(q)) return false
+      }
+      if (selectedTags.size > 0) {
+        const tags = app.tags || []
+        if (!tags.some(t => selectedTags.has(t))) return false
+      }
+      return true
+    })
+  }, [apps, searchQuery, selectedTags])
+
+  const toggleTag = (tag: string) => {
+    setSelectedTags(prev => {
+      const next = new Set(prev)
+      if (next.has(tag)) next.delete(tag)
+      else next.add(tag)
+      return next
+    })
+  }
+
   const handleAddClick = (app: MarketplaceApp) => {
     if (app.customizable && app.customizable.length > 0) {
-      // Show config form
       setConfiguringApp(app)
       const defaults: Record<string, string> = {}
       app.customizable.forEach(f => { defaults[f.key] = f.default })
       setCustomValues(defaults)
     } else {
-      // Install directly
       doInstall(app, {})
     }
   }
@@ -254,9 +294,15 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
   if (!isOpen && installingIds.size === 0) return null
   if (!isOpen) return <></> // mounted but invisible — keeps onMessage listeners alive
 
+  const tabsConfig = [
+    { id: 'marketplace' as const, label: 'Marketplace', icon: <Package size={14} /> },
+    { id: 'custom' as const, label: 'Create Custom', icon: <Sparkles size={14} /> },
+    { id: 'import' as const, label: 'Import', icon: <FolderInput size={14} /> },
+  ]
+
   return (
     <div className={styles.modalOverlay}>
-      <div className={styles.modalContent} style={{ maxWidth: '640px' }}>
+      <div className={styles.modalContent}>
         <div className={styles.modalHeader}>
           <div className={styles.headerTitle}>
             <Sparkles size={20} className={styles.headerIcon} />
@@ -267,26 +313,12 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
           </button>
         </div>
 
-        {/* Tabs */}
-        <div style={{ display: 'flex', borderBottom: '1px solid var(--border-primary)', padding: '0 var(--space-4)' }}>
-          {([
-            { id: 'marketplace' as const, label: 'Marketplace', icon: <Package size={14} /> },
-            { id: 'custom' as const, label: 'Create Custom', icon: <Sparkles size={14} /> },
-            { id: 'import' as const, label: 'Import', icon: <FolderInput size={14} /> },
-          ]).map(tab => (
+        <div className={styles.tabs}>
+          {tabsConfig.map(tab => (
             <button
               key={tab.id}
               onClick={() => setActiveTab(tab.id)}
-              style={{
-                padding: 'var(--space-2) var(--space-4)',
-                background: 'none', border: 'none',
-                borderBottom: activeTab === tab.id ? '2px solid var(--color-primary)' : '2px solid transparent',
-                color: activeTab === tab.id ? 'var(--text-primary)' : 'var(--text-muted)',
-                cursor: 'pointer',
-                fontWeight: activeTab === tab.id ? 'var(--font-semibold)' : 'var(--font-normal)',
-                fontSize: 'var(--text-sm)', fontFamily: 'inherit',
-                display: 'flex', alignItems: 'center', gap: 'var(--space-2)',
-              }}
+              className={`${styles.tab} ${activeTab === tab.id ? styles.tabActive : ''}`}
             >
               {tab.icon}
               {tab.label}
@@ -296,165 +328,202 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
 
         {/* Marketplace Tab */}
         {activeTab === 'marketplace' && !configuringApp && (
-          <div className={styles.modalBody} style={{ minHeight: '300px', maxHeight: '60vh', overflowY: 'auto' }}>
-            {marketplaceLoading ? (
-              <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '200px' }}>
-                <Loader2 size={24} style={{ animation: 'spin 1s linear infinite' }} />
-              </div>
-            ) : marketplaceError ? (
-              <div style={{ textAlign: 'center', padding: 'var(--space-6)', color: 'var(--text-muted)' }}>
-                <p style={{ marginBottom: 'var(--space-3)' }}>{marketplaceError}</p>
-                <Button size="sm" variant="secondary" onClick={fetchMarketplace}>Retry</Button>
-              </div>
-            ) : apps.length === 0 ? (
-              <div style={{ textAlign: 'center', padding: 'var(--space-6)', color: 'var(--text-muted)' }}>
-                <Package size={32} style={{ marginBottom: 'var(--space-3)', opacity: 0.5 }} />
-                <p>No apps available yet.</p>
+          <div className={styles.marketplaceBody}>
+            <div className={styles.toolbar}>
+              <div className={styles.searchWrapper}>
+                <Search size={14} className={styles.searchIcon} />
+                <input
+                  className={styles.searchInput}
+                  placeholder="Search apps..."
+                  value={searchQuery}
+                  onChange={e => setSearchQuery(e.target.value)}
+                />
               </div>
-            ) : (
-              <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-3)' }}>
-                {apps.map(app => {
-                  const appKey = app.folder || app.id
-                  return (
-                  <div key={app.id} style={{
-                    display: 'flex',
-                    alignItems: 'center',
-                    gap: 'var(--space-3)',
-                    padding: 'var(--space-3)',
-                    background: 'var(--bg-tertiary)',
-                    borderRadius: 'var(--radius-md)',
-                    border: '1px solid var(--border-primary)',
-                  }}>
-                    {app.preview ? (
-                      <img src={app.preview} alt={app.name} referrerPolicy="no-referrer"
-                        style={{ width: 80, height: 60, borderRadius: 'var(--radius-sm)', objectFit: 'cover', background: 'var(--bg-secondary)' }}
-                        onError={(e) => { (e.target as HTMLImageElement).src = ''; (e.target as HTMLImageElement).style.display = 'none' }} />
-                    ) : (
-                      <div style={{ width: 80, height: 60, borderRadius: 'var(--radius-sm)', background: 'var(--bg-secondary)', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
-                        <Package size={24} style={{ color: 'var(--text-muted)' }} />
-                      </div>
-                    )}
-                    <div style={{ flex: 1 }}>
-                      <div style={{ fontWeight: 'var(--font-semibold)', fontSize: 'var(--text-sm)', marginBottom: '2px' }}>{app.name}</div>
-                      <div style={{ fontSize: 'var(--text-xs)', color: 'var(--text-muted)', lineHeight: 1.4 }}>{app.description}</div>
-                      {app.tags && app.tags.length > 0 && (
-                        <div style={{ display: 'flex', gap: '4px', marginTop: '4px' }}>
-                          {app.tags.map(tag => (
-                            <span key={tag} style={{ fontSize: '10px', padding: '1px 6px', background: 'var(--bg-secondary)', borderRadius: 'var(--radius-sm)', color: 'var(--text-muted)' }}>{tag}</span>
-                          ))}
+              {allTags.length > 0 && (
+                <div className={styles.tagsRow}>
+                  <span className={styles.tagsLabel}>Tags:</span>
+                  <button
+                    className={`${styles.tagChip} ${selectedTags.size === 0 ? styles.tagChipActive : ''}`}
+                    onClick={() => setSelectedTags(new Set())}
+                  >
+                    All
+                  </button>
+                  {visibleTags.map(tag => (
+                    <button
+                      key={tag}
+                      className={`${styles.tagChip} ${selectedTags.has(tag) ? styles.tagChipActive : ''}`}
+                      onClick={() => toggleTag(tag)}
+                    >
+                      {tag}
+                    </button>
+                  ))}
+                  {hiddenTagCount > 0 && (
+                    <button
+                      className={styles.tagChip}
+                      onClick={() => setTagsExpanded(v => !v)}
+                    >
+                      {tagsExpanded ? 'Show less' : `+${hiddenTagCount} more`}
+                    </button>
+                  )}
+                </div>
+              )}
+            </div>
+
+            <div className={styles.marketplaceContent}>
+              {marketplaceLoading ? (
+                <div className={styles.stateCenter}>
+                  <Loader2 size={24} className={styles.spinner} />
+                </div>
+              ) : marketplaceError ? (
+                <div className={styles.stateCenter}>
+                  <p className={styles.stateText}>{marketplaceError}</p>
+                  <Button size="sm" variant="secondary" onClick={fetchMarketplace}>Retry</Button>
+                </div>
+              ) : apps.length === 0 ? (
+                <div className={styles.stateCenter}>
+                  <Package size={32} className={styles.stateIcon} />
+                  <p className={styles.stateText}>No apps available yet.</p>
+                </div>
+              ) : filteredApps.length === 0 ? (
+                <div className={styles.stateCenter}>
+                  <Search size={32} className={styles.stateIcon} />
+                  <p className={styles.stateText}>No apps match your filters.</p>
+                </div>
+              ) : (
+                <div className={styles.appsGrid}>
+                  {filteredApps.map(app => {
+                    const appKey = app.folder || app.id
+                    const installing = installingIds.has(appKey)
+                    const installedCount = installCounts.get(appKey) || 0
+                    return (
+                      <div key={app.id} className={styles.appCard}>
+                        {app.preview && !thumbFailures.has(appKey) ? (
+                          <img
+                            src={app.preview}
+                            alt={app.name}
+                            referrerPolicy="no-referrer"
+                            className={styles.appCardThumb}
+                            onError={() => setThumbFailures(prev => new Set(prev).add(appKey))}
+                          />
+                        ) : (
+                          <div className={styles.appCardPlaceholder}>
+                            <Package size={32} className={styles.appCardPlaceholderIcon} />
+                          </div>
+                        )}
+                        <div className={styles.appCardBody}>
+                          <div className={styles.appCardHeader}>
+                            <span className={styles.appCardName}>{app.name}</span>
+                            {app.version && <span className={styles.appCardVersion}>v{app.version}</span>}
+                          </div>
+                          {app.tags && app.tags.length > 0 && (
+                            <div className={styles.appCardTags}>
+                              {app.tags.map(tag => (
+                                <span key={tag} className={styles.tag}>{tag}</span>
+                              ))}
+                            </div>
+                          )}
+                          <div className={styles.appCardDesc}>{app.description}</div>
                         </div>
-                      )}
-                    </div>
-                    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'flex-end', gap: '4px', flexShrink: 0 }}>
-                      {(installCounts.get(appKey) || 0) > 0 && !installingIds.has(appKey) && (
-                        <span style={{ fontSize: '10px', color: 'var(--color-success, #22c55e)', display: 'flex', alignItems: 'center', gap: '3px', whiteSpace: 'nowrap' }}>
-                          <Check size={10} />
-                          {(installCounts.get(appKey) || 0) === 1 ? 'Installed' : `Installed ×${installCounts.get(appKey)}`}
-                        </span>
-                      )}
-                      <Button
-                        size="sm"
-                        variant="primary"
-                        icon={installingIds.has(appKey) ? <Loader2 size={14} style={{ animation: 'spin 1s linear infinite' }} /> : <Download size={14} />}
-                        onClick={() => !installingIds.has(appKey) && handleAddClick(app)}
-                        disabled={installingIds.has(appKey)}
-                      >
-                        {installingIds.has(appKey) ? 'Installing...' : 'Add'}
-                      </Button>
-                    </div>
-                  </div>
-                  )
-                })}
-              </div>
-            )}
+                        <div className={styles.appCardFooter}>
+                          {installedCount > 0 && !installing ? (
+                            <span className={styles.installedBadge}>
+                              <Check size={10} />
+                              {installedCount === 1 ? 'Installed' : `Installed ×${installedCount}`}
+                            </span>
+                          ) : <span />}
+                          <Button
+                            size="sm"
+                            variant="primary"
+                            icon={installing ? <Loader2 size={14} className={styles.spinner} /> : <Download size={14} />}
+                            onClick={() => !installing && handleAddClick(app)}
+                            disabled={installing}
+                          >
+                            {installing ? 'Installing...' : 'Add'}
+                          </Button>
+                        </div>
+                      </div>
+                    )
+                  })}
+                </div>
+              )}
+            </div>
           </div>
         )}
 
         {/* Marketplace Config Form (shown when app has customizable fields) */}
         {configuringApp && (
-          <div className={styles.modalBody}>
-            <div style={{ marginBottom: 'var(--space-3)' }}>
-              <h4 style={{ fontSize: 'var(--text-base)', fontWeight: 'var(--font-semibold)', marginBottom: 'var(--space-1)' }}>
-                Configure: {configuringApp.name}
-              </h4>
-              <p style={{ fontSize: 'var(--text-xs)', color: 'var(--text-muted)' }}>
-                Customize before installing
-              </p>
-            </div>
-            {configuringApp.customizable?.map(field => (
-              <div key={field.key} style={{ marginBottom: 'var(--space-3)' }}>
-                <label style={{ fontSize: 'var(--text-sm)', fontWeight: 'var(--font-medium)', display: 'block', marginBottom: 'var(--space-1)' }}>
-                  {field.label}
-                </label>
-                <input
-                  type={field.type || 'text'}
-                  value={customValues[field.key] || ''}
-                  onChange={(e) => setCustomValues(prev => ({ ...prev, [field.key]: e.target.value }))}
-                  placeholder={field.placeholder || field.default}
-                  style={{
-                    width: '100%',
-                    padding: 'var(--space-2) var(--space-3)',
-                    border: '1px solid var(--border-primary)',
-                    borderRadius: 'var(--radius-md)',
-                    background: 'var(--bg-primary)',
-                    color: 'var(--text-primary)',
-                    fontSize: 'var(--text-sm)',
-                    fontFamily: 'inherit',
-                  }}
-                />
+          <div className={styles.configBody}>
+            <div className={styles.configCard}>
+              <div className={styles.configHeader}>
+                <h4>Configure: {configuringApp.name}</h4>
+                <p>Customize before installing</p>
+              </div>
+              {configuringApp.customizable?.map(field => (
+                <div key={field.key} className={styles.formGroup} style={{ marginBottom: 'var(--space-3)' }}>
+                  <label className={styles.label}>{field.label}</label>
+                  <input
+                    type={field.type || 'text'}
+                    className={styles.input}
+                    value={customValues[field.key] || ''}
+                    onChange={(e) => setCustomValues(prev => ({ ...prev, [field.key]: e.target.value }))}
+                    placeholder={field.placeholder || field.default}
+                  />
+                </div>
+              ))}
+              <div className={styles.configActions}>
+                <Button variant="secondary" onClick={() => setConfiguringApp(null)}>Back</Button>
+                <Button variant="primary" icon={<Download size={14} />} onClick={() => doInstall(configuringApp, customValues)}>
+                  Install
+                </Button>
               </div>
-            ))}
-            <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 'var(--space-2)', marginTop: 'var(--space-3)' }}>
-              <Button variant="secondary" onClick={() => setConfiguringApp(null)}>Back</Button>
-              <Button variant="primary" icon={<Download size={14} />} onClick={() => doInstall(configuringApp, customValues)}>
-                Install
-              </Button>
             </div>
           </div>
         )}
 
         {/* Custom Tab */}
         {activeTab === 'custom' && (
-          <form onSubmit={handleSubmit}>
+          <form onSubmit={handleSubmit} style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>
             <div className={styles.modalBody}>
-              <div className={styles.formGroup}>
-                <label htmlFor="living-ui-name" className={styles.label}>
-                  Project Name <span className={styles.required}>*</span>
-                </label>
-                <input
-                  ref={nameInputRef}
-                  id="living-ui-name"
-                  type="text"
-                  className={`${styles.input} ${errors.name ? styles.inputError : ''}`}
-                  placeholder="e.g., World News Dashboard"
-                  value={name}
-                  onChange={e => setName(e.target.value)}
-                  maxLength={50}
-                />
-                {errors.name && <span className={styles.errorText}>{errors.name}</span>}
-              </div>
+              <div className={styles.centeredForm}>
+                <div className={styles.formGroup}>
+                  <label htmlFor="living-ui-name" className={styles.label}>
+                    Project Name <span className={styles.required}>*</span>
+                  </label>
+                  <input
+                    ref={nameInputRef}
+                    id="living-ui-name"
+                    type="text"
+                    className={`${styles.input} ${errors.name ? styles.inputError : ''}`}
+                    placeholder="e.g., World News Dashboard"
+                    value={name}
+                    onChange={e => setName(e.target.value)}
+                    maxLength={50}
+                  />
+                  {errors.name && <span className={styles.errorText}>{errors.name}</span>}
+                </div>
 
-              <div className={styles.formGroup}>
-                <label htmlFor="living-ui-description" className={styles.label}>
-                  What should this UI do? <span className={styles.required}>*</span>
-                </label>
-                <textarea
-                  id="living-ui-description"
-                  className={`${styles.textareaLarge} ${errors.description ? styles.inputError : ''}`}
-                  placeholder="Describe what you want the Living UI to display and do. Be specific about the data, layout, interactions, styling preferences, and any external APIs or data sources to use..."
-                  value={description}
-                  onChange={e => setDescription(e.target.value)}
-                  rows={10}
-                />
-                <div className={styles.descriptionFooter}>
-                  <span className={styles.hint}>
-                    The clearer and more detailed your requirements, the more accurate the Living UI will be.
-                  </span>
-                  <span className={`${styles.wordCount} ${wordCount > MAX_WORDS ? styles.wordCountError : ''}`}>
-                    {wordCount.toLocaleString()} / {MAX_WORDS.toLocaleString()} words
-                  </span>
+                <div className={styles.formGroup}>
+                  <label htmlFor="living-ui-description" className={styles.label}>
+                    What should this UI do? <span className={styles.required}>*</span>
+                  </label>
+                  <textarea
+                    id="living-ui-description"
+                    className={`${styles.textareaLarge} ${errors.description ? styles.inputError : ''}`}
+                    placeholder="Describe what you want the Living UI to display and do. Be specific about the data, layout, interactions, styling preferences, and any external APIs or data sources to use..."
+                    value={description}
+                    onChange={e => setDescription(e.target.value)}
+                    rows={12}
+                  />
+                  <div className={styles.descriptionFooter}>
+                    <span className={styles.hint}>
+                      The clearer and more detailed your requirements, the more accurate the Living UI will be.
+                    </span>
+                    <span className={`${styles.wordCount} ${wordCount > MAX_WORDS ? styles.wordCountError : ''}`}>
+                      {wordCount.toLocaleString()} / {MAX_WORDS.toLocaleString()} words
+                    </span>
+                  </div>
+                  {errors.description && <span className={styles.errorText}>{errors.description}</span>}
                 </div>
-                {errors.description && <span className={styles.errorText}>{errors.description}</span>}
               </div>
             </div>
 
@@ -471,75 +540,67 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
 
         {/* Import Tab — URL/path + ZIP upload */}
         {activeTab === 'import' && (
-          <div>
+          <div style={{ display: 'flex', flexDirection: 'column', flex: 1, minHeight: 0 }}>
             <div className={styles.modalBody}>
-              <div className={styles.formGroup}>
-                <label className={styles.label}>
-                  GitHub URL or Local Path
-                </label>
-                <input
-                  type="text"
-                  className={styles.input}
-                  placeholder="https://github.com/user/repo or /path/to/local/app"
-                  value={importSource}
-                  onChange={e => setImportSource(e.target.value)}
-                />
-                <span className={styles.hint}>
-                  Go · Node.js · Python · Rust · Docker · Static sites
-                </span>
-              </div>
+              <div className={styles.centeredForm}>
+                <div className={styles.formGroup}>
+                  <label className={styles.label}>
+                    GitHub URL or Local Path
+                  </label>
+                  <input
+                    type="text"
+                    className={styles.input}
+                    placeholder="https://github.com/user/repo or /path/to/local/app"
+                    value={importSource}
+                    onChange={e => setImportSource(e.target.value)}
+                  />
+                  <span className={styles.hint}>
+                    Go · Node.js · Python · Rust · Docker · Static sites
+                  </span>
+                </div>
 
-              <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--space-3)', margin: 'var(--space-3) 0', color: 'var(--text-muted)', fontSize: 'var(--text-xs)' }}>
-                <div style={{ flex: 1, height: 1, background: 'var(--border-primary)' }} />
-                <span>or</span>
-                <div style={{ flex: 1, height: 1, background: 'var(--border-primary)' }} />
-              </div>
+                <div className={styles.orDivider}>
+                  <span>or</span>
+                </div>
 
-              <div
-                style={{
-                  border: '2px dashed var(--border-primary)',
-                  borderRadius: 'var(--radius-lg)',
-                  padding: 'var(--space-6) var(--space-4)',
-                  textAlign: 'center',
-                  cursor: 'pointer',
-                  transition: 'border-color 0.2s, background 0.2s',
-                }}
-                onClick={() => {
-                  const input = document.createElement('input')
-                  input.type = 'file'
-                  input.accept = '.zip'
-                  input.onchange = (e) => {
-                    const file = (e.target as HTMLInputElement).files?.[0]
-                    if (file) handleZipUpload(file)
-                  }
-                  input.click()
-                }}
-                onDragOver={(e) => { e.preventDefault(); e.currentTarget.style.borderColor = 'var(--color-primary)'; e.currentTarget.style.background = 'var(--bg-tertiary)' }}
-                onDragLeave={(e) => { e.currentTarget.style.borderColor = 'var(--border-primary)'; e.currentTarget.style.background = '' }}
-                onDrop={(e) => {
-                  e.preventDefault()
-                  e.currentTarget.style.borderColor = 'var(--border-primary)'
-                  e.currentTarget.style.background = ''
-                  const file = e.dataTransfer.files[0]
-                  if (file && file.name.endsWith('.zip')) handleZipUpload(file)
-                }}
-              >
-                {importing ? (
-                  <>
-                    <Loader2 size={24} style={{ color: 'var(--color-primary)', animation: 'spin 1s linear infinite', marginBottom: 'var(--space-2)' }} />
-                    <p style={{ margin: 0, fontSize: 'var(--text-sm)', color: 'var(--text-muted)' }}>Importing...</p>
-                  </>
-                ) : (
-                  <>
-                    <Upload size={24} style={{ color: 'var(--text-muted)', marginBottom: 'var(--space-2)' }} />
-                    <p style={{ margin: 0, fontSize: 'var(--text-sm)', fontWeight: 'var(--font-medium)', color: 'var(--text-primary)' }}>
-                      Drop a ZIP file here or click to browse
-                    </p>
-                    <p style={{ margin: 'var(--space-1) 0 0', fontSize: 'var(--text-xs)', color: 'var(--text-muted)' }}>
-                      Import a previously exported Living UI
-                    </p>
-                  </>
-                )}
+                <div
+                  className={`${styles.dropZone} ${dropActive ? styles.dropZoneDragOver : ''}`}
+                  onClick={() => {
+                    const input = document.createElement('input')
+                    input.type = 'file'
+                    input.accept = '.zip'
+                    input.onchange = (e) => {
+                      const file = (e.target as HTMLInputElement).files?.[0]
+                      if (file) handleZipUpload(file)
+                    }
+                    input.click()
+                  }}
+                  onDragOver={(e) => { e.preventDefault(); setDropActive(true) }}
+                  onDragLeave={() => setDropActive(false)}
+                  onDrop={(e) => {
+                    e.preventDefault()
+                    setDropActive(false)
+                    const file = e.dataTransfer.files[0]
+                    if (file && file.name.endsWith('.zip')) handleZipUpload(file)
+                  }}
+                >
+                  {importing ? (
+                    <>
+                      <Loader2 size={24} className={styles.spinner} />
+                      <p className={styles.dropZoneSub}>Importing...</p>
+                    </>
+                  ) : (
+                    <>
+                      <Upload size={24} className={styles.dropZoneIcon} />
+                      <p className={styles.dropZoneLabel}>
+                        Drop a ZIP file here or click to browse
+                      </p>
+                      <p className={styles.dropZoneSub}>
+                        Import a previously exported Living UI
+                      </p>
+                    </>
+                  )}
+                </div>
               </div>
             </div>
 
@@ -549,7 +610,7 @@ export function CreateLivingUIModal({ isOpen, onClose, onSubmit, onInstalled }:
               </Button>
               <Button
                 variant="primary"
-                icon={importing ? <Loader2 size={16} style={{ animation: 'spin 1s linear infinite' }} /> : <FolderInput size={16} />}
+                icon={importing ? <Loader2 size={16} className={styles.spinner} /> : <FolderInput size={16} />}
                 disabled={!importSource.trim() || importing}
                 onClick={async () => {
                   setImporting(true)
diff --git a/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.module.css b/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.module.css
new file mode 100644
index 00000000..75e1b4e2
--- /dev/null
+++ b/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.module.css
@@ -0,0 +1,230 @@
+/* SkillCreatorModal — input/choice modal for creating/improving a skill from a task */
+.modalOverlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(0, 0, 0, 0.6);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: var(--z-modal);
+  padding: var(--space-4);
+  animation: fadeIn 0.15s ease-out;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.modalContent {
+  background: var(--bg-secondary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-lg);
+  width: 100%;
+  max-width: 460px;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  animation: slideUp 0.15s ease-out;
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.modalHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--space-4);
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.modalHeader h3 {
+  font-size: var(--text-lg);
+  font-weight: var(--font-semibold);
+  color: var(--text-primary);
+  margin: 0;
+}
+
+.modalClose {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-md);
+  color: var(--text-muted);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+
+.modalClose:hover {
+  background: var(--bg-hover);
+  color: var(--text-primary);
+}
+
+.modalBody {
+  padding: var(--space-4);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.intro {
+  font-size: var(--text-sm);
+  color: var(--text-secondary);
+  margin: 0;
+  line-height: 1.5;
+}
+
+.choiceGroup {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+}
+
+.choiceItem {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: all var(--transition-fast);
+}
+
+.choiceItem:hover {
+  background: var(--bg-hover);
+}
+
+.choiceItem.choiceItemSelected {
+  border-color: var(--color-primary);
+  background: var(--color-primary-subtle);
+}
+
+.choiceRadio {
+  margin-top: 2px;
+}
+
+.choiceLabel {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+}
+
+.choiceHint {
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+}
+
+.fieldLabel {
+  font-size: var(--text-sm);
+  font-weight: var(--font-medium);
+  color: var(--text-primary);
+  margin: 0;
+}
+
+.fieldInput {
+  width: 100%;
+  padding: var(--space-2) var(--space-3);
+  background: var(--bg-primary);
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  color: var(--text-primary);
+  font-size: var(--text-sm);
+  font-family: var(--font-mono, monospace);
+  transition: border-color var(--transition-fast);
+}
+
+.fieldInput:focus {
+  outline: none;
+  border-color: var(--color-primary);
+}
+
+.fieldInput.fieldInputError {
+  border-color: var(--color-error);
+}
+
+.fieldHint {
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+  margin: 0;
+}
+
+.fieldError {
+  font-size: var(--text-xs);
+  color: var(--color-error);
+  margin: 0;
+}
+
+.modalFooter {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--space-2);
+  padding: var(--space-4);
+  border-top: 1px solid var(--border-primary);
+}
+
+/* ─── Success view ─────────────────────────────────────────────── */
+.successIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 56px;
+  height: 56px;
+  margin: 0 auto;
+  border-radius: 50%;
+  background: rgba(16, 185, 129, 0.15);
+  color: var(--color-success, #10b981);
+}
+
+.successHeadline {
+  font-size: var(--text-base);
+  font-weight: var(--font-semibold);
+  color: var(--text-primary);
+  text-align: center;
+  margin: 0;
+}
+
+.successHeadline code {
+  font-family: var(--font-mono, monospace);
+  background: var(--bg-primary);
+  padding: 2px 6px;
+  border-radius: var(--radius-sm);
+  font-size: 0.95em;
+}
+
+/* ─── Submitting indicator ─────────────────────────────────────── */
+.submittingText {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: var(--text-xs);
+  color: var(--text-muted);
+  margin: 0;
+}
+
+@keyframes spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+.spinning {
+  animation: spin 1s linear infinite;
+}
diff --git a/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.tsx b/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.tsx
new file mode 100644
index 00000000..0b62031d
--- /dev/null
+++ b/app/ui_layer/browser/frontend/src/components/ui/SkillCreatorModal.tsx
@@ -0,0 +1,269 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { X, Check, Loader2 } from 'lucide-react'
+import { Button } from './Button'
+import styles from './SkillCreatorModal.module.css'
+
+export type SkillCreatorMode = 'create' | 'improve'
+
+export interface SkillCreatorSubmit {
+  mode: SkillCreatorMode
+  skillName?: string
+  targetSkill?: string
+}
+
+export interface SkillCreatorSuccessInfo {
+  skillName: string
+  mode: SkillCreatorMode
+}
+
+export interface SkillCreatorModalProps {
+  isOpen: boolean
+  sourceSkills: string[]
+  reservedNames: Set<string>
+  status: 'idle' | 'submitting' | 'success' | 'error'
+  serverError: string | null
+  successInfo: SkillCreatorSuccessInfo | null
+  onClose: () => void
+  onSubmit: (payload: SkillCreatorSubmit) => void
+}
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]{1,63}$/
+
+type Choice = { kind: 'create' } | { kind: 'improve'; skill: string }
+
+function choiceKey(c: Choice): string {
+  return c.kind === 'create' ? 'create' : `improve:${c.skill}`
+}
+
+export function SkillCreatorModal({
+  isOpen,
+  sourceSkills,
+  reservedNames,
+  status,
+  serverError,
+  successInfo,
+  onClose,
+  onSubmit,
+}: SkillCreatorModalProps) {
+  const submitting = status === 'submitting'
+  const isSuccess = status === 'success'
+
+  const choices = useMemo<Choice[]>(() => {
+    const list: Choice[] = [{ kind: 'create' }]
+    for (const s of sourceSkills) {
+      list.push({ kind: 'improve', skill: s })
+    }
+    return list
+  }, [sourceSkills])
+
+  const [selectedKey, setSelectedKey] = useState<string>(choiceKey(choices[0]))
+  const [skillName, setSkillName] = useState<string>('')
+
+  // Reset the form ONLY on the closed→open transition, not on every
+  // `choices` change. This keeps the form intact while submitting (when
+  // the parent may re-render and pass a new `choices` reference).
+  const wasOpenRef = useRef(false)
+  useEffect(() => {
+    if (isOpen && !wasOpenRef.current) {
+      setSelectedKey(choiceKey(choices[0]))
+      setSkillName('')
+    }
+    wasOpenRef.current = isOpen
+  }, [isOpen, choices])
+
+  const selected = choices.find(c => choiceKey(c) === selectedKey) ?? choices[0]
+  const isCreateMode = selected.kind === 'create'
+
+  const validationError = useMemo<string | null>(() => {
+    if (!isCreateMode) return null
+    const trimmed = skillName.trim()
+    if (!trimmed) return null
+    if (!NAME_PATTERN.test(trimmed)) {
+      return 'Use lowercase letters, digits, and hyphens. Must start with a letter, 2–64 chars.'
+    }
+    if (reservedNames.has(trimmed)) {
+      return 'This name is reserved. Pick another.'
+    }
+    return null
+  }, [isCreateMode, skillName, reservedNames])
+
+  const canSubmit = !submitting && !isSuccess && (
+    isCreateMode
+      ? skillName.trim().length > 0 && !validationError
+      : true
+  )
+
+  if (!isOpen) return null
+
+  const handleSubmit = () => {
+    if (!canSubmit) return
+    if (selected.kind === 'create') {
+      onSubmit({ mode: 'create', skillName: skillName.trim() })
+    } else {
+      onSubmit({ mode: 'improve', targetSkill: selected.skill })
+    }
+  }
+
+  const handleOverlayClick = () => {
+    // While submitting, clicking the overlay does nothing — the request is
+    // in flight and we don't want to lose track of it.
+    if (submitting) return
+    onClose()
+  }
+
+  // ─────────────────────────── SUCCESS VIEW ───────────────────────────
+  // After the backend acknowledges, the modal stays open showing a
+  // confirmation. The actual workflow runs in the background; the user
+  // dismisses the modal manually.
+  if (isSuccess && successInfo) {
+    const isCreate = successInfo.mode === 'create'
+    const verbing = isCreate ? 'Creating' : 'Improving'
+    return (
+      <div className={styles.modalOverlay} onClick={handleOverlayClick}>
+        <div className={styles.modalContent} onClick={e => e.stopPropagation()}>
+          <div className={styles.modalHeader}>
+            <h3>Skill workflow started</h3>
+            <button
+              className={styles.modalClose}
+              onClick={onClose}
+              aria-label="Close"
+            >
+              <X size={16} />
+            </button>
+          </div>
+          <div className={styles.modalBody}>
+            <div className={styles.successIcon}>
+              <Check size={28} />
+            </div>
+            <p className={styles.successHeadline}>
+              {verbing} <code>{successInfo.skillName}</code>…
+            </p>
+            <p className={styles.intro}>
+              The agent is working on it now. You'll see progress in chat
+              and the new task will appear in the task panel. Feel free to
+              close this dialog.
+            </p>
+          </div>
+          <div className={styles.modalFooter}>
+            <Button variant="primary" onClick={onClose}>
+              Close
+            </Button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  // ──────────────────────────── FORM VIEW ────────────────────────────
+  const showRadio = sourceSkills.length > 0
+
+  return (
+    <div className={styles.modalOverlay} onClick={handleOverlayClick}>
+      <div className={styles.modalContent} onClick={e => e.stopPropagation()}>
+        <div className={styles.modalHeader}>
+          <h3>Create skill from task</h3>
+          <button
+            className={styles.modalClose}
+            onClick={onClose}
+            aria-label="Close"
+            disabled={submitting}
+          >
+            <X size={16} />
+          </button>
+        </div>
+        <div className={styles.modalBody}>
+          <p className={styles.intro}>
+            CraftBot will read this task's record and turn it into a reusable skill.
+            The new (or edited) skill will be invocable on future tasks.
+          </p>
+
+          {showRadio && (
+            <div className={styles.choiceGroup} role="radiogroup">
+              {choices.map(c => {
+                const key = choiceKey(c)
+                const isSel = key === selectedKey
+                const label = c.kind === 'create'
+                  ? 'Create a new skill'
+                  : `Improve "${c.skill}"`
+                const hint = c.kind === 'create'
+                  ? 'Distil this task into a brand-new skill.'
+                  : 'Refine the existing skill using this task as evidence.'
+                return (
+                  <label
+                    key={key}
+                    className={`${styles.choiceItem} ${isSel ? styles.choiceItemSelected : ''}`}
+                  >
+                    <input
+                      type="radio"
+                      className={styles.choiceRadio}
+                      name="skill-creator-choice"
+                      checked={isSel}
+                      onChange={() => setSelectedKey(key)}
+                      disabled={submitting}
+                    />
+                    <span className={styles.choiceLabel}>
+                      <strong>{label}</strong>
+                      <span className={styles.choiceHint}>{hint}</span>
+                    </span>
+                  </label>
+                )
+              })}
+            </div>
+          )}
+
+          {isCreateMode && (
+            <>
+              <label className={styles.fieldLabel} htmlFor="skill-creator-name">
+                New skill name
+              </label>
+              <input
+                id="skill-creator-name"
+                type="text"
+                className={`${styles.fieldInput} ${validationError ? styles.fieldInputError : ''}`}
+                placeholder="my-new-skill"
+                value={skillName}
+                onChange={e => setSkillName(e.target.value)}
+                disabled={submitting}
+                autoFocus
+                onKeyDown={e => {
+                  if (e.key === 'Enter') handleSubmit()
+                }}
+              />
+              {validationError ? (
+                <p className={styles.fieldError}>{validationError}</p>
+              ) : (
+                <p className={styles.fieldHint}>
+                  Lowercase letters, digits, and hyphens. Example: <code>weekly-pr-summary</code>.
+                </p>
+              )}
+            </>
+          )}
+
+          {submitting && (
+            <p className={styles.submittingText}>
+              <Loader2 size={14} className={styles.spinning} />
+              {' '}Submitting — waiting for the agent to acknowledge…
+            </p>
+          )}
+
+          {serverError && (
+            <p className={styles.fieldError}>{serverError}</p>
+          )}
+        </div>
+        <div className={styles.modalFooter}>
+          <Button variant="secondary" onClick={onClose} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button
+            variant="primary"
+            onClick={handleSubmit}
+            disabled={!canSubmit}
+            loading={submitting}
+          >
+            {isCreateMode ? 'Create' : 'Improve'}
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/app/ui_layer/browser/frontend/src/components/ui/index.ts b/app/ui_layer/browser/frontend/src/components/ui/index.ts
index 8f16e2f7..094084ba 100644
--- a/app/ui_layer/browser/frontend/src/components/ui/index.ts
+++ b/app/ui_layer/browser/frontend/src/components/ui/index.ts
@@ -16,3 +16,6 @@ export { AttachmentDisplay } from './AttachmentDisplay'
 
 export { ConfirmModal } from './ConfirmModal'
 export type { ConfirmModalProps } from './ConfirmModal'
+
+export { SkillCreatorModal } from './SkillCreatorModal'
+export type { SkillCreatorModalProps, SkillCreatorMode, SkillCreatorSubmit } from './SkillCreatorModal'
diff --git a/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx b/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
index 5f27ae3b..481d95b7 100644
--- a/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
+++ b/app/ui_layer/browser/frontend/src/contexts/WebSocketContext.tsx
@@ -1,16 +1,19 @@
 import React, { createContext, useContext, useEffect, useRef, useState, useCallback, ReactNode } from 'react'
+import { useNavigate } from 'react-router-dom'
 import type {
   ChatMessage, ActionItem, AgentStatus, InitialState, WSMessage, DashboardMetrics,
   TaskCancelResponse, FilteredDashboardMetrics, MetricsTimePeriod, OnboardingStep,
-  OnboardingStepResponse, OnboardingSubmitResponse, OnboardingCompleteResponse, 
-  LocalLLMState, LocalLLMCheckResponse, LocalLLMTestResponse, LocalLLMInstallResponse, 
+  OnboardingStepResponse, OnboardingSubmitResponse, OnboardingCompleteResponse,
+  LocalLLMState, LocalLLMCheckResponse, LocalLLMTestResponse, LocalLLMInstallResponse,
   LocalLLMProgressResponse, LocalLLMPullProgressResponse, SuggestedModel,
+  SkillMeta,
   // Living UI types
   LivingUIProject, LivingUICreateRequest, LivingUIStatusUpdate, LivingUIStateUpdate,
   LivingUITodo, LivingUITodosUpdate,
   LivingUICreateResponse, LivingUIListResponse, LivingUILaunchResponse, LivingUIStopResponse, LivingUIDeleteResponse
 } from '../types'
 import { getWsUrl } from '../utils/connection'
+import { scheduleRefreshIframe } from '../pages/LivingUI/iframePool'
 
 // Pending attachment type for upload
 interface PendingAttachment {
@@ -83,6 +86,7 @@ interface WebSocketState {
   livingUITodos: Record<string, LivingUITodo[]>
   activeLivingUIId: string | null
   livingUIStates: Record<string, LivingUIStateUpdate['state']>
+  skillMeta: SkillMeta
 }
 
 interface WebSocketContextType extends WebSocketState {
@@ -195,6 +199,11 @@ const defaultState: WebSocketState = {
   livingUITodos: {},
   activeLivingUIId: null,
   livingUIStates: {},
+  skillMeta: {
+    internalWorkflowIds: [],
+    internalSkillNames: [],
+    reservedSkillNames: [],
+  },
 }
 
 const WebSocketContext = createContext<WebSocketContextType | undefined>(undefined)
@@ -202,6 +211,9 @@ const WebSocketContext = createContext<WebSocketContextType | undefined>(undefin
 export function WebSocketProvider({ children }: { children: ReactNode }) {
   const [state, setState] = useState<WebSocketState>(defaultState)
   const wsRef = useRef<WebSocket | null>(null)
+  const navigate = useNavigate()
+  const navigateRef = useRef(navigate)
+  navigateRef.current = navigate
   const reconnectTimeoutRef = useRef<number | null>(null)
   const isConnectingRef = useRef<boolean>(false)
   const reconnectCountRef = useRef<number>(0)
@@ -355,6 +367,19 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
         break
       }
 
+      case 'skill_meta': {
+        const data = msg.data as unknown as SkillMeta
+        setState(prev => ({
+          ...prev,
+          skillMeta: {
+            internalWorkflowIds: data.internalWorkflowIds || [],
+            internalSkillNames: data.internalSkillNames || [],
+            reservedSkillNames: data.reservedSkillNames || [],
+          },
+        }))
+        break
+      }
+
       case 'chat_message': {
         const message = msg.data as unknown as ChatMessage
         setState(prev => {
@@ -446,6 +471,24 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
         break
       }
 
+      case 'task_token_update': {
+        const { id, inputTokens, outputTokens, cacheTokens } = msg.data as {
+          id: string
+          inputTokens: number
+          outputTokens: number
+          cacheTokens: number
+        }
+        setState(prev => ({
+          ...prev,
+          actions: prev.actions.map(a =>
+            a.id === id
+              ? { ...a, inputTokens, outputTokens, cacheTokens }
+              : a
+          ),
+        }))
+        break
+      }
+
       case 'action_remove': {
         const { id } = msg.data as { id: string }
         setState(prev => ({
@@ -947,6 +990,12 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
         break
       }
 
+      case 'living_ui_data_changed': {
+        const { projectId } = msg.data as { projectId: string }
+        if (projectId) scheduleRefreshIframe(projectId)
+        break
+      }
+
       case 'living_ui_error': {
         const { projectId, error } = msg.data as { projectId: string; error: string }
         setState(prev => ({
@@ -960,6 +1009,12 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
         }))
         break
       }
+
+      case 'navigate': {
+        const { path } = (msg.data || {}) as { path?: string }
+        if (path) navigateRef.current(path)
+        break
+      }
     }
   }, [])
 
@@ -1018,19 +1073,26 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
   ) => {
     const clientId = newClientId()
 
-    // Optimistic insert: show the user's bubble immediately at reduced opacity.
-    // The server echo (case 'chat_message') will replace this entry in place by
-    // matching on clientId, flipping `pending` -> false.
-    const optimistic: ChatMessage = {
-      sender: 'You',
-      content,
-      style: 'user',
-      timestamp: Date.now() / 1000,
-      messageId: `pending:${clientId}`,
-      clientId,
-      pending: true,
+    // Slash commands are handled by the controller's command executor and
+    // never produce a user chat bubble — skip the optimistic insert so a
+    // "pending" bubble doesn't linger when the server has nothing to echo.
+    const isSlashCommand = content.trimStart().startsWith('/')
+
+    if (!isSlashCommand) {
+      // Optimistic insert: show the user's bubble immediately at reduced opacity.
+      // The server echo (case 'chat_message') will replace this entry in place by
+      // matching on clientId, flipping `pending` -> false.
+      const optimistic: ChatMessage = {
+        sender: 'You',
+        content,
+        style: 'user',
+        timestamp: Date.now() / 1000,
+        messageId: `pending:${clientId}`,
+        clientId,
+        pending: true,
+      }
+      setState(prev => ({ ...prev, messages: [...prev.messages, optimistic] }))
     }
-    setState(prev => ({ ...prev, messages: [...prev.messages, optimistic] }))
 
     sendOrQueue(JSON.stringify({
       type: 'message',
@@ -1043,10 +1105,8 @@ export function WebSocketProvider({ children }: { children: ReactNode }) {
   }, [sendOrQueue])
 
   const sendCommand = useCallback((command: string) => {
-    if (wsRef.current?.readyState === WebSocket.OPEN) {
-      wsRef.current.send(JSON.stringify({ type: 'command', command }))
-    }
-  }, [])
+    sendOrQueue(JSON.stringify({ type: 'command', command }))
+  }, [sendOrQueue])
 
   const clearMessages = useCallback(() => {
     setState(prev => ({ ...prev, messages: [] }))
diff --git a/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx b/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
index d8557a0c..44b06aca 100644
--- a/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Chat/ChatMessage.tsx
@@ -81,7 +81,7 @@ export const ChatMessageItem = memo(function ChatMessageItem({
         <div className={styles.messageHeader}>
           <span className={styles.sender}>{message.sender}</span>
           <span className={styles.timestamp}>
-            {new Date(message.timestamp * 1000).toLocaleTimeString()}
+            {new Date(message.timestamp * 1000).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })}
           </span>
         </div>
         {/* Reply context callout - shown above user message when replying */}
diff --git a/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css b/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
index 492ddb76..d9c2d34a 100644
--- a/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Chat/ChatPage.module.css
@@ -332,152 +332,6 @@
   color: var(--text-muted);
 }
 
-.inputListening {
-  border-color: var(--color-primary);
-  box-shadow: 0 0 0 2px var(--color-primary-subtle);
-}
-
-/* Mic + language selector */
-.micGroup {
-  display: flex;
-  align-items: center;
-  position: relative;
-  gap: 0;
-  border: 1px solid var(--border-primary);
-  border-radius: var(--radius-lg);
-}
-
-.micCombo {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  position: relative;
-  background: transparent;
-  border: none;
-  color: var(--text-secondary);
-  cursor: pointer;
-  padding: 6px;
-  border-radius: var(--radius-lg) 0 0 var(--radius-lg);
-  outline: none;
-  transition: color 0.15s, background 0.15s;
-}
-
-.micCombo:hover {
-  color: var(--text-primary);
-  background: var(--bg-tertiary);
-}
-
-.micCombo.micComboActive {
-  color: var(--color-error, #ef4444);
-}
-
-.micIconWrap {
-  position: relative;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-}
-
-/* Pulsing ring around mic icon when recording */
-.micPulseRing {
-  position: absolute;
-  inset: -3px;
-  border-radius: 50%;
-  border: 2px solid var(--color-error, #ef4444);
-  animation: micRingPulse 1.4s ease-in-out infinite;
-  pointer-events: none;
-}
-
-@keyframes micRingPulse {
-  0%, 100% { transform: scale(1); opacity: 0.8; }
-  50% { transform: scale(1.25); opacity: 0; }
-}
-
-.langBtn {
-  display: flex;
-  align-items: center;
-  align-self: stretch;
-  background: transparent;
-  border: none;
-  border-left: 1px solid var(--border-primary);
-  color: var(--text-secondary);
-  font-size: 10px;
-  font-family: inherit;
-  font-weight: 600;
-  cursor: pointer;
-  padding: 0 8px;
-  border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
-  line-height: 1;
-  outline: none;
-  white-space: nowrap;
-  transition: color 0.15s, background 0.15s;
-}
-
-.langBtn:hover:not(:disabled) {
-  background: var(--bg-tertiary);
-  color: var(--text-primary);
-}
-
-.langBtn:disabled {
-  opacity: 0.4;
-  cursor: not-allowed;
-}
-
-.langBtn.langBtnActive {
-  color: var(--color-error, #ef4444);
-}
-
-.langDropdown {
-  position: absolute;
-  bottom: calc(100% + 6px);
-  left: 0;
-  background: var(--bg-secondary);
-  border: 1px solid var(--border-primary);
-  border-radius: var(--radius-md);
-  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.5);
-  overflow: hidden;
-  z-index: 999;
-  min-width: 130px;
-}
-
-.langOption {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  width: 100%;
-  background: transparent;
-  border: none;
-  color: var(--text-secondary);
-  font-family: inherit;
-  font-size: var(--text-sm);
-  padding: 7px 12px;
-  cursor: pointer;
-  text-align: left;
-}
-
-.langOption:hover {
-  background: var(--bg-tertiary);
-  color: var(--text-primary);
-}
-
-.langOptionActive {
-  color: var(--color-primary);
-}
-
-.langCode {
-  font-weight: 600;
-  font-size: 11px;
-  width: 36px;
-  flex-shrink: 0;
-}
-
-.langFull {
-  font-size: 11px;
-  opacity: 0.8;
-}
-
 /* Action Panel - Right Side (resizable) */
 .actionPanel {
   display: flex;
diff --git a/app/ui_layer/browser/frontend/src/pages/Dashboard/DashboardPage.tsx b/app/ui_layer/browser/frontend/src/pages/Dashboard/DashboardPage.tsx
index eea85888..3a5dd717 100644
--- a/app/ui_layer/browser/frontend/src/pages/Dashboard/DashboardPage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Dashboard/DashboardPage.tsx
@@ -147,7 +147,7 @@ export function DashboardPage() {
   // Calculate statistics from actions
   const tasks = useMemo(() => actions.filter(a => a.itemType === 'task'), [actions])
   const completedTasks = useMemo(() => tasks.filter(t => t.status === 'completed').length, [tasks])
-  const failedTasks = useMemo(() => tasks.filter(t => t.status === 'error').length, [tasks])
+  const failedTasks = useMemo(() => tasks.filter(t => t.status === 'error' || t.status === 'cancelled').length, [tasks])
   const runningTasks = useMemo(() => tasks.filter(t => t.status === 'running').length, [tasks])
   const totalActions = useMemo(() => actions.filter(a => a.itemType === 'action').length, [actions])
 
diff --git a/app/ui_layer/browser/frontend/src/pages/LivingUI/iframePool.ts b/app/ui_layer/browser/frontend/src/pages/LivingUI/iframePool.ts
index e20d7cd7..54426f41 100644
--- a/app/ui_layer/browser/frontend/src/pages/LivingUI/iframePool.ts
+++ b/app/ui_layer/browser/frontend/src/pages/LivingUI/iframePool.ts
@@ -89,6 +89,18 @@ export function refreshIframe(id: string) {
   }
 }
 
+const pendingRefreshTimers = new Map<string, ReturnType<typeof setTimeout>>()
+
+export function scheduleRefreshIframe(id: string, delayMs = 500) {
+  const existing = pendingRefreshTimers.get(id)
+  if (existing) clearTimeout(existing)
+  const timer = setTimeout(() => {
+    pendingRefreshTimers.delete(id)
+    refreshIframe(id)
+  }, delayMs)
+  pendingRefreshTimers.set(id, timer)
+}
+
 export function hasIframe(id: string): boolean {
   return pool.has(id)
 }
diff --git a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
index 88f3ff8c..e23ac229 100644
--- a/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Onboarding/OnboardingPage.tsx
@@ -340,9 +340,19 @@ export function OnboardingPage() {
     removeAgentProfilePicture,
   } = useWebSocket()
 
+  // Providers that route through OpenRouter — model slug is configurable.
+  const OR_PROXIED = ['moonshot', 'minimax']
+  const OR_MODEL_DEFAULTS: Record<string, string> = {
+    moonshot: 'moonshotai/kimi-k2.5',
+    minimax: 'minimax/minimax-01',
+  }
+
   // Local form state
   const [selectedValue, setSelectedValue] = useState<string | string[]>('')
   const [textValue, setTextValue] = useState('')
+  const [orModel, setOrModel] = useState('')
+  // For proxied providers: 'direct' tries the native API, 'openrouter' routes via OR.
+  const [proxiedVia, setProxiedVia] = useState<'direct' | 'openrouter'>('direct')
   // URL submitted from OllamaSetup
   const [ollamaUrl, setOllamaUrl] = useState('http://localhost:11434')
   const [ollamaConnected, setOllamaConnected] = useState(false)
@@ -405,6 +415,11 @@ export function OnboardingPage() {
       } else {
         setSelectedValue('')
         setTextValue(typeof onboardingStep.default === 'string' ? onboardingStep.default : '')
+        // Reset proxied-provider mode and pre-fill OR model default
+        if (onboardingStep.name === 'api_key' && onboardingStep.provider && OR_PROXIED.includes(onboardingStep.provider)) {
+          setProxiedVia('direct')
+          setOrModel(OR_MODEL_DEFAULTS[onboardingStep.provider] || '')
+        }
       }
     }
   }, [onboardingStep])
@@ -477,9 +492,13 @@ export function OnboardingPage() {
   const handleSubmit = useCallback(() => {
     if (!onboardingStep) return
     const isOllamaStep = onboardingStep.name === 'api_key' && onboardingStep.provider === 'remote'
+    const isProxiedStep = onboardingStep.name === 'api_key' &&
+      onboardingStep.provider != null && OR_PROXIED.includes(onboardingStep.provider)
 
     if (isOllamaStep) {
       submitOnboardingStep(ollamaUrl)
+    } else if (isProxiedStep) {
+      submitOnboardingStep({ api_key: textValue, via: proxiedVia, or_model: proxiedVia === 'openrouter' ? orModel : '' })
     } else if (onboardingStep.form_fields && onboardingStep.form_fields.length > 0) {
       submitOnboardingStep(formValues)
     } else if (onboardingStep.options.length > 0) {
@@ -487,7 +506,7 @@ export function OnboardingPage() {
     } else {
       submitOnboardingStep(textValue)
     }
-  }, [onboardingStep, selectedValue, textValue, ollamaUrl, formValues, submitOnboardingStep])
+  }, [onboardingStep, selectedValue, textValue, orModel, proxiedVia, ollamaUrl, formValues, submitOnboardingStep])
 
   const handleSkip = useCallback(() => skipOnboardingStep(), [skipOnboardingStep])
   const handleBack = useCallback(() => goBackOnboardingStep(), [goBackOnboardingStep])
@@ -821,6 +840,60 @@ export function OnboardingPage() {
 
     // Text input step
     const isApiKey = onboardingStep.name === 'api_key'
+    const isProxied = isApiKey && onboardingStep.provider != null && OR_PROXIED.includes(onboardingStep.provider)
+
+    if (isProxied) {
+      const providerDisplay = { moonshot: 'Moonshot', minimax: 'MiniMax' }[onboardingStep.provider!] ?? onboardingStep.provider
+      const isViaOR = proxiedVia === 'openrouter'
+      return (
+        <div className={styles.formGroup}>
+          <input
+            type="password"
+            className={`${styles.textInput} ${onboardingError ? styles.error : ''}`}
+            value={textValue}
+            onChange={e => setTextValue(e.target.value)}
+            placeholder={isViaOR ? 'Enter your OpenRouter API key' : `Enter your ${providerDisplay} API key`}
+            autoFocus
+            onKeyDown={e => { if (e.key === 'Enter' && canSubmit) handleSubmit() }}
+          />
+          <div className={styles.inputHint}>Your API key is stored locally.</div>
+          {isViaOR && (
+            <div style={{ marginTop: 14 }}>
+              <label style={{ display: 'block', fontSize: '0.85rem', fontWeight: 500, marginBottom: 6 }}>
+                Model <span style={{ fontWeight: 400, opacity: 0.6 }}>(optional — leave default or enter any OpenRouter slug)</span>
+              </label>
+              <input
+                type="text"
+                className={styles.textInput}
+                value={orModel}
+                onChange={e => setOrModel(e.target.value)}
+                placeholder={OR_MODEL_DEFAULTS[onboardingStep.provider!] ?? 'e.g. moonshotai/kimi-k2.5'}
+              />
+            </div>
+          )}
+          <div style={{ marginTop: 12 }}>
+            {isViaOR ? (
+              <button
+                type="button"
+                onClick={() => { setProxiedVia('direct'); setTextValue('') }}
+                style={{ background: 'none', border: 'none', color: 'var(--accent, #e07b39)', cursor: 'pointer', fontSize: '0.82rem', padding: 0 }}
+              >
+                ← Use direct {providerDisplay} API instead
+              </button>
+            ) : (
+              <button
+                type="button"
+                onClick={() => { setProxiedVia('openrouter'); setTextValue('') }}
+                style={{ background: 'none', border: 'none', color: 'var(--accent, #e07b39)', cursor: 'pointer', fontSize: '0.82rem', padding: 0 }}
+              >
+                Having connection issues? Use OpenRouter instead →
+              </button>
+            )}
+          </div>
+        </div>
+      )
+    }
+
     return (
       <div className={styles.formGroup}>
         <input
@@ -871,7 +944,11 @@ export function OnboardingPage() {
           {onboardingStep && (
             <>
               <h2 className={styles.stepTitle}>
-                {onboardingStep.title}
+                {(() => {
+                  const isProxiedApiKey = onboardingStep.name === 'api_key' && onboardingStep.provider != null && OR_PROXIED.includes(onboardingStep.provider)
+                  if (isProxiedApiKey && proxiedVia === 'openrouter') return 'Enter OpenRouter API Key'
+                  return onboardingStep.title
+                })()}
                 {!onboardingStep.required && (
                   <span className={styles.optionalBadge}>Optional</span>
                 )}
@@ -893,7 +970,14 @@ export function OnboardingPage() {
                     case 'error':         return localLLM.error ?? "Something went wrong. Check the error below and retry."
                     default:              return "Checking Ollama status…"
                   }
-                })() : onboardingStep.description}
+                })() : (() => {
+                  const isProxiedApiKey = onboardingStep.name === 'api_key' && onboardingStep.provider != null && OR_PROXIED.includes(onboardingStep.provider)
+                  if (isProxiedApiKey && proxiedVia === 'openrouter') {
+                    const display = { moonshot: 'Moonshot (Kimi)', minimax: 'MiniMax' }[onboardingStep.provider!] ?? onboardingStep.provider
+                    return `${display} models will be accessed via OpenRouter. Enter your OpenRouter API key — the model will be configured automatically. Get a free key at openrouter.ai`
+                  }
+                  return onboardingStep.description
+                })()}
               </p>
 
               {/* Error Message */}
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
index a5cca7ff..1c32551c 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/GeneralSettings.tsx
@@ -11,6 +11,8 @@ import {
   RefreshCw,
   Upload,
   Trash2,
+  Eraser,
+  ListChecks,
 } from 'lucide-react'
 import { Button, Badge, ConfirmModal } from '../../components/ui'
 import { useTheme } from '../../contexts/ThemeContext'
@@ -58,6 +60,15 @@ export function GeneralSettings() {
   const [isSaving, setIsSaving] = useState(false)
   const [saveStatus, setSaveStatus] = useState<'idle' | 'success' | 'error'>('idle')
 
+  // Clear Conversation / Clear Tasks state
+  const [isClearingConversation, setIsClearingConversation] = useState(false)
+  const [clearConversationStatus, setClearConversationStatus] =
+    useState<'idle' | 'success' | 'error'>('idle')
+  const [isClearingTasks, setIsClearingTasks] = useState(false)
+  const [clearTasksStatus, setClearTasksStatus] =
+    useState<'idle' | 'success' | 'error'>('idle')
+  const [clearTasksRemoved, setClearTasksRemoved] = useState<number | null>(null)
+
   // Agent profile picture
   const [profilePictureUrl, setProfilePictureUrl] = useState<string>(agentProfilePictureUrl)
   const [hasCustomPicture, setHasCustomPicture] = useState<boolean>(agentProfilePictureHasCustom)
@@ -205,6 +216,22 @@ export function GeneralSettings() {
         setResetStatus(d.success ? 'success' : 'error')
         setTimeout(() => setResetStatus('idle'), 3000)
       }),
+      onMessage('clear_conversation', (data: unknown) => {
+        const d = data as { success: boolean }
+        setIsClearingConversation(false)
+        setClearConversationStatus(d.success ? 'success' : 'error')
+        setTimeout(() => setClearConversationStatus('idle'), 3000)
+      }),
+      onMessage('clear_tasks', (data: unknown) => {
+        const d = data as { success: boolean; removed?: number }
+        setIsClearingTasks(false)
+        setClearTasksStatus(d.success ? 'success' : 'error')
+        setClearTasksRemoved(typeof d.removed === 'number' ? d.removed : null)
+        setTimeout(() => {
+          setClearTasksStatus('idle')
+          setClearTasksRemoved(null)
+        }, 3000)
+      }),
       onMessage('agent_file_read', (data: unknown) => {
         const d = data as { filename: string; content: string; success: boolean }
         if (d.filename === 'USER.md') {
@@ -391,6 +418,30 @@ export function GeneralSettings() {
     })
   }
 
+  const handleClearConversation = () => {
+    confirm({
+      title: 'Clear Conversation',
+      message: 'Clear the chat history? Tasks (including running ones) and dashboard data are preserved.',
+      confirmText: 'Clear',
+      variant: 'danger',
+    }, () => {
+      setIsClearingConversation(true)
+      send('clear_conversation')
+    })
+  }
+
+  const handleClearTasks = () => {
+    confirm({
+      title: 'Clear Tasks',
+      message: 'Remove completed, failed, and aborted tasks from the panel? Running tasks remain visible. Dashboard usage data and task statistics will be preserved.',
+      confirmText: 'Clear',
+      variant: 'danger',
+    }, () => {
+      setIsClearingTasks(true)
+      send('clear_tasks')
+    })
+  }
+
   const handleSaveUserMd = () => {
     setIsSavingUserMd(true)
     send('agent_file_write', { filename: 'USER.md', content: userMdContent })
@@ -632,6 +683,84 @@ export function GeneralSettings() {
         )}
       </div>
 
+      {/* Clear Data Section — compact */}
+      <div className={styles.dangerZone}>
+        <div className={styles.dangerRowList}>
+          <div className={styles.dangerRow}>
+            <Eraser size={16} className={styles.dangerRowIcon} />
+            <div className={styles.dangerRowInfo}>
+              <h4 className={styles.dangerRowTitle}>Clear Conversation</h4>
+              <p className={styles.dangerRowHint}>
+                Remove chat messages. Tasks and dashboard data are preserved.
+              </p>
+            </div>
+            <div className={styles.dangerRowAction}>
+              {clearConversationStatus === 'success' && (
+                <span className={styles.statusSuccess}>
+                  <Check size={14} /> Cleared
+                </span>
+              )}
+              {clearConversationStatus === 'error' && (
+                <span className={styles.statusError}>
+                  <X size={14} /> Failed
+                </span>
+              )}
+              <Button
+                variant="danger"
+                size="sm"
+                onClick={handleClearConversation}
+                disabled={isClearingConversation}
+                icon={
+                  isClearingConversation
+                    ? <Loader2 size={14} className={styles.spinning} />
+                    : <Eraser size={14} />
+                }
+              >
+                {isClearingConversation ? 'Clearing...' : 'Clear'}
+              </Button>
+            </div>
+          </div>
+
+          <div className={styles.dangerRow}>
+            <ListChecks size={16} className={styles.dangerRowIcon} />
+            <div className={styles.dangerRowInfo}>
+              <h4 className={styles.dangerRowTitle}>Clear Tasks</h4>
+              <p className={styles.dangerRowHint}>
+                Remove completed, failed, and aborted tasks. Running tasks and dashboard data are preserved.
+              </p>
+            </div>
+            <div className={styles.dangerRowAction}>
+              {clearTasksStatus === 'success' && (
+                <span className={styles.statusSuccess}>
+                  <Check size={14} />
+                  {clearTasksRemoved !== null
+                    ? ` ${clearTasksRemoved} cleared`
+                    : ' Cleared'}
+                </span>
+              )}
+              {clearTasksStatus === 'error' && (
+                <span className={styles.statusError}>
+                  <X size={14} /> Failed
+                </span>
+              )}
+              <Button
+                variant="danger"
+                size="sm"
+                onClick={handleClearTasks}
+                disabled={isClearingTasks}
+                icon={
+                  isClearingTasks
+                    ? <Loader2 size={14} className={styles.spinning} />
+                    : <ListChecks size={14} />
+                }
+              >
+                {isClearingTasks ? 'Clearing...' : 'Clear'}
+              </Button>
+            </div>
+          </div>
+        </div>
+      </div>
+
       {/* Reset Section */}
       <div className={styles.dangerZone}>
         <div className={styles.dangerHeader}>
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
index fb8d67fb..909eb86b 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/IntegrationsSettings.tsx
@@ -1,4 +1,5 @@
 import React, { useState, useEffect } from 'react'
+import * as LucideIcons from 'lucide-react'
 import {
   Globe,
   Package,
@@ -9,6 +10,7 @@ import {
   X,
   Power,
   Wrench,
+  HelpCircle,
 } from 'lucide-react'
 import { Button, Badge, ConfirmModal } from '../../components/ui'
 import { useToast } from '../../contexts/ToastContext'
@@ -29,6 +31,17 @@ interface IntegrationAccount {
   id: string
 }
 
+// Schema for a single config input rendered by the Configure section in
+// the Manage modal. Sourced from the backend handler's ``config_fields``.
+interface ConfigField {
+  key: string
+  label: string
+  type: 'text' | 'textarea' | 'list' | 'checkbox' | 'select' | 'number'
+  placeholder?: string
+  help?: string
+  options?: Array<{ value: string; label: string }>  // required when type==='select'
+}
+
 interface Integration {
   id: string
   name: string
@@ -37,10 +50,21 @@ interface Integration {
   connected: boolean
   accounts: IntegrationAccount[]
   fields: IntegrationField[]
+  icon?: string  // Lucide icon name supplied by the backend handler
+  has_config?: boolean
+  config_fields?: ConfigField[] | null
+  // Inline help shown in a popover when the user clicks the "?" button
+  // in the connect modal. Each entry is one step / one place to look.
+  // Sourced from the handler's ``connect_help`` attribute. Null/empty
+  // hides the "?" button.
+  connect_help?: string[] | null
 }
 
-// Integration icon component using inline SVGs for brand logos
-const IntegrationIcon = ({ id, size = 20 }: { id: string; size?: number }) => {
+// Integration icon component. Lookup order:
+//   1. Hand-crafted brand SVG keyed by integration id (defined below)
+//   2. Lucide icon by name from the backend's ``icon`` field
+//   3. Generic globe fallback
+const IntegrationIcon = ({ id, icon, size = 20 }: { id: string; icon?: string; size?: number }) => {
   const icons: Record<string, React.ReactNode> = {
     google: (
       <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
@@ -50,6 +74,46 @@ const IntegrationIcon = ({ id, size = 20 }: { id: string; size?: number }) => {
         <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" fill="#EA4335"/>
       </svg>
     ),
+    gmail: (
+      <svg width={size} height={size} viewBox="0 0 256 193" xmlns="http://www.w3.org/2000/svg">
+        <path fill="#4285F4" d="M58.182 192.05V93.14L27.507 65.077 0 49.504v125.091c0 9.658 7.825 17.455 17.455 17.455z"/>
+        <path fill="#34A853" d="M197.818 192.05h40.727c9.659 0 17.455-7.826 17.455-17.455V49.505l-31.156 17.837-27.026 25.798z"/>
+        <path fill="#EA4335" d="M58.182 93.14l-4.174-38.605 4.174-36.927L128 69.864l69.818-52.364 4.671 33.654-4.67 39.987-69.819 52.363z"/>
+        <path fill="#FBBC04" d="M197.818 17.5V93.14L256 49.504V26.231c0-21.585-24.64-33.89-41.89-20.945z"/>
+        <path fill="#C5221F" d="M0 49.504l26.759 20.07L58.182 93.14V17.5L41.89 5.286C24.61-7.658 0 4.646 0 26.226z"/>
+      </svg>
+    ),
+    google_calendar: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <rect x="2" y="4" width="20" height="18" rx="2" fill="#fff" stroke="#dadce0" strokeWidth="0.5"/>
+        <rect x="2" y="4" width="20" height="4" rx="2" fill="#4285F4"/>
+        <rect x="6" y="2" width="2" height="4" rx="1" fill="#4285F4"/>
+        <rect x="16" y="2" width="2" height="4" rx="1" fill="#4285F4"/>
+        <text x="12" y="18" fontSize="10" fontWeight="700" textAnchor="middle" fill="#1a73e8" fontFamily="sans-serif">{new Date().getDate()}</text>
+      </svg>
+    ),
+    google_drive: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <path d="M9 2L1.5 15l3 5h7.5L9 2z" fill="#0F9D58"/>
+        <path d="M15 2L9 2l9 16h6L15 2z" fill="#FFCD40"/>
+        <path d="M4.5 20l3-5h15l-3 5h-15z" fill="#4285F4"/>
+      </svg>
+    ),
+    google_docs: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <path d="M5 2h9l5 5v13a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2z" fill="#4285F4"/>
+        <path d="M14 2v5h5l-5-5z" fill="#A1C2FA"/>
+        <rect x="6" y="11" width="12" height="1.2" rx="0.6" fill="#fff"/>
+        <rect x="6" y="14" width="12" height="1.2" rx="0.6" fill="#fff"/>
+        <rect x="6" y="17" width="9" height="1.2" rx="0.6" fill="#fff"/>
+      </svg>
+    ),
+    google_youtube: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <path d="M23 7.2a3 3 0 0 0-2.1-2.1C19 4.5 12 4.5 12 4.5s-7 0-8.9.6A3 3 0 0 0 1 7.2C.5 9.1.5 12 .5 12s0 2.9.5 4.8a3 3 0 0 0 2.1 2.1c1.9.6 8.9.6 8.9.6s7 0 8.9-.6a3 3 0 0 0 2.1-2.1c.5-1.9.5-4.8.5-4.8s0-2.9-.5-4.8z" fill="#FF0000"/>
+        <path d="M9.75 15.5l6-3.5-6-3.5v7z" fill="#fff"/>
+      </svg>
+    ),
     slack: (
       <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
         <path d="M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52zm1.271 0a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313z" fill="#E01E5A"/>
@@ -83,6 +147,24 @@ const IntegrationIcon = ({ id, size = 20 }: { id: string; size?: number }) => {
         <path d="M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z"/>
       </svg>
     ),
+    line: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="#06C755">
+        <path d="M19.365 9.863c.349 0 .63.285.63.631 0 .345-.281.63-.63.63H17.61v1.125h1.755c.349 0 .63.283.63.63 0 .344-.281.629-.63.629h-2.386c-.345 0-.627-.285-.627-.629V8.108c0-.345.282-.63.63-.63h2.386c.346 0 .627.285.627.63 0 .349-.281.63-.63.63H17.61v1.125h1.755zm-3.855 3.016c0 .27-.174.51-.432.596-.064.021-.133.031-.199.031-.211 0-.391-.09-.51-.25l-2.443-3.317v2.94c0 .344-.279.629-.631.629-.346 0-.626-.285-.626-.629V8.108c0-.27.173-.51.43-.595.06-.023.136-.033.194-.033.195 0 .375.104.495.254l2.462 3.33V8.108c0-.345.282-.63.63-.63.345 0 .63.285.63.63v4.771zm-5.741 0c0 .344-.282.629-.631.629-.345 0-.627-.285-.627-.629V8.108c0-.345.282-.63.63-.63.346 0 .628.285.628.63v4.771zm-2.466.629H4.917c-.345 0-.63-.285-.63-.629V8.108c0-.345.285-.63.63-.63.348 0 .63.285.63.63v4.141h1.756c.348 0 .629.283.629.63 0 .344-.282.629-.629.629M24 10.314C24 4.943 18.615.572 12 .572S0 4.943 0 10.314c0 4.811 4.27 8.842 10.035 9.608.391.082.923.258 1.058.59.12.301.079.766.038 1.08l-.164 1.02c-.045.301-.24 1.186 1.049.645 1.291-.539 6.916-4.078 9.436-6.975C23.176 14.393 24 12.458 24 10.314"/>
+      </svg>
+    ),
+    lark: (
+      <svg width={size} height={size} viewBox="0 0 24 24" fill="none">
+        <defs>
+          <linearGradient id="larkGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+            <stop offset="0%" stopColor="#00D6B9"/>
+            <stop offset="50%" stopColor="#00B8E0"/>
+            <stop offset="100%" stopColor="#3370FF"/>
+          </linearGradient>
+        </defs>
+        <rect x="2" y="2" width="20" height="20" rx="4.5" fill="url(#larkGrad)"/>
+        <path d="M7.5 9.2c0-.66.54-1.2 1.2-1.2h6.4c.66 0 1.2.54 1.2 1.2v2.4c0 1.66-1.34 3-3 3H10.6l-2.6 2.2c-.3.25-.5.05-.5-.3v-7.3z" fill="#fff"/>
+      </svg>
+    ),
     whatsapp: (
       <svg width={size} height={size} viewBox="0 0 24 24" fill="#25D366">
         <path d="M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413Z"/>
@@ -118,7 +200,165 @@ const IntegrationIcon = ({ id, size = 20 }: { id: string; size?: number }) => {
       </svg>
     ),
   }
-  return <span className={styles.integrationIconSvg}>{icons[id] || <Globe size={size} />}</span>
+  // 1. Brand SVG keyed by the backend's ``icon`` name (e.g. "github",
+  //    "google", "notion") — the integration file owns this declaration.
+  if (icon && icons[icon]) {
+    return <span className={styles.integrationIconSvg}>{icons[icon]}</span>
+  }
+  // 2. Backwards-compat: legacy lookup by integration id, in case any
+  //    integration hasn't declared ``icon`` yet.
+  if (icons[id]) {
+    return <span className={styles.integrationIconSvg}>{icons[id]}</span>
+  }
+  // 3. Lucide fallback for non-brand icons (e.g. "Inbox", "Send").
+  if (icon) {
+    const lucideMap = LucideIcons as unknown as Record<string, React.ComponentType<{ size?: number }>>
+    const LucideIcon = lucideMap[icon]
+    if (LucideIcon) {
+      return <span className={styles.integrationIconSvg}><LucideIcon size={size} /></span>
+    }
+  }
+  // 4. Generic fallback
+  return <span className={styles.integrationIconSvg}><Globe size={size} /></span>
+}
+
+// Schema-driven Configure form. Renders one input per ``ConfigField`` and
+// flushes its values back to the parent via ``onChange``. Adding a new
+// supported ``type`` is one ``case`` in the renderField switch — no other
+// file changes needed.
+const ConfigForm = ({
+  integrationId,
+  schema,
+  values,
+  onChange,
+  saving,
+  onSave,
+}: {
+  integrationId: string
+  schema: ConfigField[]
+  values: Record<string, any>
+  onChange: (values: Record<string, any>) => void
+  saving: boolean
+  onSave: () => void
+}) => {
+  const setField = (key: string, value: any) => {
+    onChange({ ...values, [key]: value })
+  }
+
+  const renderField = (field: ConfigField) => {
+    const cur = values[field.key]
+    const id = `cfg-${integrationId}-${field.key}`
+
+    switch (field.type) {
+      case 'textarea':
+        return (
+          <textarea
+            id={id}
+            className={styles.input}
+            placeholder={field.placeholder}
+            value={cur ?? ''}
+            onChange={e => setField(field.key, e.target.value)}
+            rows={4}
+          />
+        )
+
+      case 'list': {
+        // Comma-separated <input>. The backend coerces "a, b, c" → ["a","b","c"]
+        // on save (see service.py:_coerce). Crucially, we keep the raw string
+        // in state while the user is typing — converting to an array on every
+        // keystroke would strip trailing commas/spaces and stop the user from
+        // typing a second item.
+        const display = Array.isArray(cur) ? cur.join(', ') : (cur ?? '')
+        return (
+          <input
+            id={id}
+            type="text"
+            className={styles.input}
+            placeholder={field.placeholder}
+            value={display}
+            onChange={e => setField(field.key, e.target.value)}
+          />
+        )
+      }
+
+      case 'checkbox':
+        return (
+          <label htmlFor={id} style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer' }}>
+            <input
+              id={id}
+              type="checkbox"
+              checked={Boolean(cur)}
+              onChange={e => setField(field.key, e.target.checked)}
+            />
+            <span>{field.help || field.label}</span>
+          </label>
+        )
+
+      case 'select':
+        return (
+          <select
+            id={id}
+            className={styles.input}
+            value={cur ?? ''}
+            onChange={e => setField(field.key, e.target.value)}
+          >
+            {(field.options ?? []).map(opt => (
+              <option key={opt.value} value={opt.value}>{opt.label}</option>
+            ))}
+          </select>
+        )
+
+      case 'number':
+        return (
+          <input
+            id={id}
+            type="number"
+            className={styles.input}
+            placeholder={field.placeholder}
+            value={cur ?? ''}
+            onChange={e => setField(field.key, e.target.value)}
+          />
+        )
+
+      case 'text':
+      default:
+        return (
+          <input
+            id={id}
+            type="text"
+            className={styles.input}
+            placeholder={field.placeholder}
+            value={cur ?? ''}
+            onChange={e => setField(field.key, e.target.value)}
+          />
+        )
+    }
+  }
+
+  return (
+    <div className={styles.connectForm}>
+      {schema.map(field => (
+        <div key={field.key} className={styles.fieldGroup}>
+          {/* Checkbox renders its own label (next to the box). For every
+              other type the label sits above the input. */}
+          {field.type !== 'checkbox' && (
+            <label htmlFor={`cfg-${integrationId}-${field.key}`} className={styles.fieldLabel}>
+              {field.label}
+            </label>
+          )}
+          {renderField(field)}
+          {field.help && field.type !== 'checkbox' && (
+            <p style={{ fontSize: 12, opacity: 0.65, marginTop: 4 }}>{field.help}</p>
+          )}
+        </div>
+      ))}
+      <div className={styles.modalActions}>
+        <Button variant="primary" onClick={onSave} disabled={saving}>
+          {saving ? <><Loader2 size={14} className={styles.spinning} /> Saving…</> : 'Save'}
+        </Button>
+      </div>
+    </div>
+  )
 }
 
 export function IntegrationsSettings() {
@@ -144,11 +384,29 @@ export function IntegrationsSettings() {
   const [credentials, setCredentials] = useState<Record<string, string>>({})
   const [connectError, setConnectError] = useState('')
   const [isConnecting, setIsConnecting] = useState(false)
+  const [showConnectHelp, setShowConnectHelp] = useState(false)
 
   // Manage modal state
   const [showManageModal, setShowManageModal] = useState(false)
   const [managingIntegration, setManagingIntegration] = useState<Integration | null>(null)
 
+  // Slow operation overlay — shown during long disconnects (WhatsApp Web's
+  // bridge teardown can take 20–30 seconds; without this the user has no
+  // feedback until the backend confirms). Cleared by integration_disconnect_result.
+  const [pendingOp, setPendingOp] = useState<{
+    kind: 'disconnect'
+    id: string
+    label: string
+  } | null>(null)
+
+  // Per-integration runtime config — populated from integration_get_config
+  // when the Manage modal opens for an integration with has_config === true.
+  // ``configValues`` is keyed by config_field.key. The form is fully driven
+  // by ``managingIntegration.config_fields`` (the schema from the backend).
+  const [configValues, setConfigValues] = useState<Record<string, any>>({})
+  const [configLoading, setConfigLoading] = useState(false)
+  const [configSaving, setConfigSaving] = useState(false)
+
   // WhatsApp QR code state
   const [whatsappQrCode, setWhatsappQrCode] = useState<string | null>(null)
   const [whatsappSessionId, setWhatsappSessionId] = useState<string | null>(null)
@@ -194,7 +452,10 @@ export function IntegrationsSettings() {
         }
       }),
       onMessage('integration_disconnect_result', (data: unknown) => {
-        const d = data as { success: boolean; message?: string; error?: string }
+        const d = data as { success: boolean; message?: string; error?: string; id?: string }
+        // Clear the slow-disconnect overlay if this result is for the
+        // operation it was tracking.
+        setPendingOp(prev => (prev && d.id && prev.id === d.id) ? null : prev)
         if (d.success) {
           showToast('success', d.message || 'Disconnected successfully')
           setShowManageModal(false)
@@ -208,10 +469,45 @@ export function IntegrationsSettings() {
         if (d.success && d.integration) {
           setManagingIntegration(d.integration)
           setShowManageModal(true)
+          // If this integration has runtime config, kick off a fetch so the
+          // Configure section is populated by the time the user scrolls to it.
+          if (d.integration.has_config) {
+            setConfigLoading(true)
+            setConfigValues({})
+            send('integration_get_config', { id: d.integration.id })
+          }
         } else {
           showToast('error', d.error || 'Failed to get integration info')
         }
       }),
+      // Per-integration runtime config (schema-driven; works for every
+      // integration that declares config_class on its handler).
+      onMessage('integration_config', (data: unknown) => {
+        const d = data as {
+          id: string; success: boolean
+          schema?: ConfigField[]; values?: Record<string, any>
+          error?: string
+        }
+        setConfigLoading(false)
+        if (d.success) {
+          setConfigValues(d.values || {})
+        } else if (d.error) {
+          showToast('error', d.error)
+        }
+      }),
+      onMessage('integration_config_updated', (data: unknown) => {
+        const d = data as {
+          id: string; success: boolean
+          message?: string; values?: Record<string, any>; error?: string
+        }
+        setConfigSaving(false)
+        if (d.success) {
+          showToast('success', d.message || 'Settings saved')
+          if (d.values) setConfigValues(d.values)
+        } else {
+          showToast('error', d.error || d.message || 'Failed to save settings')
+        }
+      }),
       // WhatsApp QR code handlers
       onMessage('whatsapp_qr_result', (data: unknown) => {
         const d = data as { success: boolean; session_id?: string; qr_code?: string; status?: string; message?: string }
@@ -284,9 +580,10 @@ export function IntegrationsSettings() {
     setSelectedIntegration(integration)
     setCredentials({})
     setConnectError('')
+    setShowConnectHelp(false)
     setShowConnectModal(true)
 
-    if (integration.auth_type === 'interactive' && integration.id === 'whatsapp') {
+    if (integration.auth_type === 'interactive' && integration.id === 'whatsapp_web') {
       handleStartWhatsAppQR()
     }
   }
@@ -351,20 +648,42 @@ export function IntegrationsSettings() {
     send('integration_connect_interactive', { id: selectedIntegration.id })
   }
 
+  // Slow integrations show a "working…" overlay during disconnect so the
+  // user gets visible feedback during the bridge teardown (which can take
+  // 20–30 seconds for WhatsApp Web). Add other slow integrations here.
+  const SLOW_DISCONNECT_IDS = new Set(['whatsapp_web'])
+
   const handleDisconnect = (accountId?: string) => {
     if (!managingIntegration) return
+    const targetId = managingIntegration.id
+    const targetName = managingIntegration.name
+
+    // Optimistic UI update — mark this integration as disconnected immediately
+    // so the user gets instant feedback in the integrations list. Some
+    // integrations (WhatsApp Web) take 20+ seconds to tear down their bridge
+    // cleanly, and the ``integration_list`` broadcast only fires after that
+    // completes. The backend's authoritative ``integration_list`` will
+    // overwrite this when it arrives. If the disconnect fails,
+    // ``integration_disconnect_result`` shows a toast and the next refresh
+    // restores the real state.
+    setIntegrations(prev => prev.map(i =>
+      i.id === targetId ? { ...i, connected: false, accounts: [] } : i
+    ))
+    setConnectedCount(prev => Math.max(0, prev - 1))
+    setShowManageModal(false)
+    setManagingIntegration(null)
+
+    // Slow disconnects: show a blocking overlay until the result arrives.
+    if (SLOW_DISCONNECT_IDS.has(targetId)) {
+      setPendingOp({ kind: 'disconnect', id: targetId, label: targetName })
+    }
+
     send('integration_disconnect', {
-      id: managingIntegration.id,
+      id: targetId,
       account_id: accountId,
     })
   }
 
-  const handleAddAnother = () => {
-    if (!managingIntegration) return
-    setShowManageModal(false)
-    handleOpenConnect(managingIntegration)
-  }
-
   const filteredIntegrations = integrations
     .filter(integration => {
       if (!searchQuery) return true
@@ -434,7 +753,7 @@ export function IntegrationsSettings() {
               className={`${styles.integrationItem} ${!integration.connected ? styles.integrationItemDisabled : ''}`}
             >
               <div className={styles.integrationItemIcon}>
-                <IntegrationIcon id={integration.id} size={24} />
+                <IntegrationIcon id={integration.id} icon={integration.icon} size={24} />
               </div>
               <div className={styles.integrationItemMain}>
                 <div className={styles.integrationItemHeader}>
@@ -497,10 +816,46 @@ export function IntegrationsSettings() {
           <div className={styles.modalContent} onClick={e => e.stopPropagation()}>
             <div className={styles.modalHeader}>
               <h3>Connect {selectedIntegration.name}</h3>
-              <button className={styles.modalClose} onClick={() => setShowConnectModal(false)}>
-                <X size={18} />
-              </button>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+                {(selectedIntegration.connect_help?.length ?? 0) > 0 && (
+                  <button
+                    className={styles.modalClose}
+                    onClick={() => setShowConnectHelp(v => !v)}
+                    title={`Where to find ${selectedIntegration.name} credentials`}
+                    aria-expanded={showConnectHelp}
+                  >
+                    <HelpCircle size={18} />
+                  </button>
+                )}
+                <button className={styles.modalClose} onClick={() => setShowConnectModal(false)}>
+                  <X size={18} />
+                </button>
+              </div>
             </div>
+            {showConnectHelp && (selectedIntegration.connect_help?.length ?? 0) > 0 && (
+              <div
+                style={{
+                  margin: '0 var(--space-4, 1rem)',
+                  marginTop: '12px',
+                  padding: 'var(--space-3, 0.75rem) var(--space-4, 1rem)',
+                  background: 'var(--bg-tertiary)',
+                  border: '1px solid var(--border-primary)',
+                  borderRadius: 'var(--radius-md, 6px)',
+                  color: 'var(--text-primary)',
+                  fontSize: 'var(--text-sm, 0.85rem)',
+                  lineHeight: 1.5,
+                }}
+              >
+                <div style={{ fontWeight: 600, marginBottom: 6, color: 'var(--text-primary)' }}>
+                  Where to find {selectedIntegration.name} credentials
+                </div>
+                <ol style={{ margin: 0, paddingLeft: '1.25rem', color: 'var(--text-secondary)' }}>
+                  {selectedIntegration.connect_help!.map((step, i) => (
+                    <li key={i} style={{ marginBottom: 2 }}>{step}</li>
+                  ))}
+                </ol>
+              </div>
+            )}
             <div className={styles.modalBody}>
               {/* OAuth-only integrations */}
               {selectedIntegration.auth_type === 'oauth' && (
@@ -669,8 +1024,31 @@ export function IntegrationsSettings() {
                 </div>
               )}
 
-              {/* Interactive integrations (WhatsApp) */}
-              {selectedIntegration.auth_type === 'interactive' && (
+              {/* Interactive integrations: generic dispatcher for non-WhatsApp */}
+              {selectedIntegration.auth_type === 'interactive' && selectedIntegration.id !== 'whatsapp_web' && (
+                <div className={styles.connectForm}>
+                  <p className={styles.connectDesc}>
+                    {selectedIntegration.description}
+                  </p>
+                  <Button
+                    variant="primary"
+                    onClick={handleConnectInteractive}
+                    disabled={isConnecting}
+                  >
+                    {isConnecting ? (
+                      <><Loader2 size={16} className={styles.spinning} /> Connecting...</>
+                    ) : (
+                      <>Connect {selectedIntegration.name}</>
+                    )}
+                  </Button>
+                  {connectError && (
+                    <div className={styles.connectError}>{connectError}</div>
+                  )}
+                </div>
+              )}
+
+              {/* WhatsApp Web QR-specific interactive flow */}
+              {selectedIntegration.auth_type === 'interactive' && selectedIntegration.id === 'whatsapp_web' && (
                 <div className={styles.connectForm}>
                   {whatsappStatus === 'loading' && (
                     <div className={styles.whatsappLoading}>
@@ -756,17 +1134,58 @@ export function IntegrationsSettings() {
                   ))}
                 </div>
               )}
-              <div className={styles.modalActions}>
-                <Button variant="secondary" onClick={handleAddAnother} icon={<Plus size={14} />}>
-                  Add Another Account
-                </Button>
-              </div>
+              {/* Configure — schema-driven form, only shown for integrations
+                  whose handler declared ``config_class`` + ``config_fields``. */}
+              {managingIntegration.has_config && (managingIntegration.config_fields?.length ?? 0) > 0 && (
+                <>
+                  <h4 className={styles.manageSubtitle}>Configure</h4>
+                  {configLoading ? (
+                    <div style={{ display: 'flex', alignItems: 'center', gap: 8, opacity: 0.7 }}>
+                      <Loader2 size={16} className={styles.spinning} />
+                      <span>Loading settings…</span>
+                    </div>
+                  ) : (
+                    <ConfigForm
+                      integrationId={managingIntegration.id}
+                      schema={managingIntegration.config_fields ?? []}
+                      values={configValues}
+                      onChange={setConfigValues}
+                      saving={configSaving}
+                      onSave={() => {
+                        setConfigSaving(true)
+                        send('integration_update_config', {
+                          id: managingIntegration.id,
+                          values: configValues,
+                        })
+                      }}
+                    />
+                  )}
+                </>
+              )}
             </div>
           </div>
         </div>
       )}
 
       {/* Confirm Modal */}
+      {/* Slow-disconnect overlay — shown until the backend confirms via
+          ``integration_disconnect_result``. */}
+      {pendingOp && (
+        <div className={styles.modalOverlay}>
+          <div className={styles.modalContent} style={{ minWidth: 320, maxWidth: 400 }}>
+            <div className={styles.whatsappLoading}>
+              <Loader2 size={48} className={styles.spinning} />
+              <p style={{ marginTop: 16, fontWeight: 500 }}>
+                {pendingOp.kind === 'disconnect' ? `Disconnecting ${pendingOp.label}…` : `Connecting ${pendingOp.label}…`}
+              </p>
+              <p style={{ marginTop: 8, fontSize: 12, opacity: 0.7 }}>
+                This can take up to 30 seconds.
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+
       <ConfirmModal {...confirmModalProps} />
     </div>
   )
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/LivingUISettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/LivingUISettings.tsx
index 2fedbb0c..f00ea7bf 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/LivingUISettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/LivingUISettings.tsx
@@ -169,11 +169,16 @@ export function LivingUISettings() {
   }, [isConnected, send, onMessage])
 
   useEffect(() => {
-    const cleanup = onMessage('living_ui_project_action', (data: any) => {
+    const handleActionComplete = (data: any) => {
       setActionInProgress(null)
       if (data.success) send('living_ui_settings_get')
-    })
-    return cleanup
+    }
+    const cleanups = [
+      onMessage('living_ui_launch', handleActionComplete),
+      onMessage('living_ui_stop', handleActionComplete),
+      onMessage('living_ui_delete', handleActionComplete),
+    ]
+    return () => cleanups.forEach(c => c())
   }, [send, onMessage])
 
   useEffect(() => {
@@ -228,12 +233,12 @@ export function LivingUISettings() {
 
   const handleLaunch = (projectId: string) => {
     setActionInProgress(projectId)
-    send('living_ui_project_action', { projectId, action: 'launch' })
+    send('living_ui_launch', { projectId })
   }
 
   const handleStop = (projectId: string) => {
     setActionInProgress(projectId)
-    send('living_ui_project_action', { projectId, action: 'stop' })
+    send('living_ui_stop', { projectId })
   }
 
   const toggleProject = (id: string) => {
@@ -253,7 +258,7 @@ export function LivingUISettings() {
       variant: 'danger',
     }, () => {
       setActionInProgress(project.id)
-      send('living_ui_project_action', { projectId: project.id, action: 'delete' })
+      send('living_ui_delete', { projectId: project.id })
     })
   }
 
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
index 984015ec..ba1e4eca 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/ModelSettings.tsx
@@ -9,6 +9,11 @@ import { useToast } from '../../contexts/ToastContext'
 import styles from './SettingsPage.module.css'
 import { useSettingsWebSocket } from './useSettingsWebSocket'
 import { getOllamaInstallPercent } from '../../utils/ollamaInstall'
+import {
+  OpenRouterModelPicker,
+  OpenRouterCreditsBanner,
+  useOpenRouterCatalog,
+} from './OpenRouterModelPicker'
 
 // Types
 interface ProviderInfo {
@@ -20,6 +25,7 @@ interface ProviderInfo {
   llm_model: string | null
   vlm_model: string | null
   has_vlm: boolean
+  supports_catalog?: boolean
 }
 
 interface ApiKeyStatus {
@@ -93,6 +99,16 @@ export function ModelSettings() {
   const [pullBytes, setPullBytes] = useState<{ completed: number; total: number; percent: number } | null>(null)
   const [pullStatus, setPullStatus] = useState('')
 
+  // OpenRouter catalog — fetched once on first OpenRouter selection,
+  // shared between the LLM and VLM pickers below.
+  const orCatalog = useOpenRouterCatalog(
+    send,
+    onMessage,
+    isConnected,
+    provider === 'openrouter',
+    newBaseUrl || baseUrls['openrouter'] || undefined,
+  )
+
   const fmtBytes = (n: number) => {
     if (n >= 1_073_741_824) return `${(n / 1_073_741_824).toFixed(1)} GB`
     if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(0)} MB`
@@ -205,6 +221,7 @@ export function ModelSettings() {
           setNewVlmModel(prev => {
             const effective = prev || currentVlmModel
             if (!d.models.includes(effective)) {
+              setHasChanges(true)
               return d.models[0]
             }
             return prev
@@ -347,10 +364,13 @@ export function ModelSettings() {
 
   const handleTestConnection = () => {
     setIsTesting(true)
+    // Send the user's actual model so the test exercises it; otherwise a
+    // typo passes the test (auth-only) and only fails at first real call.
     send('model_connection_test', {
       provider,
       apiKey: newApiKey || undefined,
       baseUrl: newBaseUrl || baseUrls[provider],
+      model: newLlmModel || currentLlmModel || undefined,
     })
   }
 
@@ -365,6 +385,7 @@ export function ModelSettings() {
         provider,
         apiKey: newApiKey || undefined,
         baseUrl: newBaseUrl || baseUrls[provider],
+        model: newLlmModel || currentLlmModel || undefined,
       })
     } else {
       setIsSaving(true)
@@ -420,28 +441,40 @@ export function ModelSettings() {
           {/* Model Configuration */}
           {currentProvider && (
             <>
-              <div className={styles.formGroup}>
-                <label>LLM Model</label>
-                {provider === 'remote' && ollamaModels.length > 0 ? (
-                  <select
-                    value={newLlmModel || currentLlmModel || ''}
-                    onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
-                  >
-                    {ollamaModels.map(m => <option key={m} value={m}>{m}</option>)}
-                  </select>
-                ) : (
-                  <input
-                    type="text"
-                    value={newLlmModel || currentLlmModel || ''}
-                    onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
-                    placeholder={
-                      provider === 'remote' && ollamaModelsLoading
-                        ? 'Loading models...'
-                        : currentLlmModel || 'Enter LLM model name...'
-                    }
-                  />
-                )}
-              </div>
+              {provider === 'openrouter' && currentProvider.supports_catalog ? (
+                <OpenRouterModelPicker
+                  models={orCatalog.models}
+                  loading={orCatalog.loading}
+                  error={orCatalog.error}
+                  onRefresh={orCatalog.refresh}
+                  label="LLM Model"
+                  value={newLlmModel || currentLlmModel || ''}
+                  onChange={(v) => { setNewLlmModel(v); setHasChanges(true) }}
+                />
+              ) : (
+                <div className={styles.formGroup}>
+                  <label>LLM Model</label>
+                  {provider === 'remote' && ollamaModels.length > 0 ? (
+                    <select
+                      value={newLlmModel || currentLlmModel || ''}
+                      onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
+                    >
+                      {ollamaModels.map(m => <option key={m} value={m}>{m}</option>)}
+                    </select>
+                  ) : (
+                    <input
+                      type="text"
+                      value={newLlmModel || currentLlmModel || ''}
+                      onChange={(e) => { setNewLlmModel(e.target.value); setHasChanges(true) }}
+                      placeholder={
+                        provider === 'remote' && ollamaModelsLoading
+                          ? 'Loading models...'
+                          : currentLlmModel || 'Enter LLM model name...'
+                      }
+                    />
+                  )}
+                </div>
+              )}
 
               {/* Download new Ollama model / Install Ollama */}
               {provider === 'remote' && (
@@ -605,6 +638,18 @@ export function ModelSettings() {
               )}
 
               {currentProvider.has_vlm && (
+                provider === 'openrouter' && currentProvider.supports_catalog ? (
+                  <OpenRouterModelPicker
+                    models={orCatalog.models}
+                    loading={orCatalog.loading}
+                    error={orCatalog.error}
+                    onRefresh={orCatalog.refresh}
+                    label="VLM Model"
+                    requireVision
+                    value={newVlmModel || currentVlmModel || ''}
+                    onChange={(v) => { setNewVlmModel(v); setHasChanges(true) }}
+                  />
+                ) : (
                 <div className={styles.formGroup}>
                   <label>VLM Model</label>
                   {(() => {
@@ -636,6 +681,7 @@ export function ModelSettings() {
                     )
                   })()}
                 </div>
+                )
               )}
             </>
           )}
@@ -660,9 +706,26 @@ export function ModelSettings() {
                 onChange={(e) => { setNewApiKey(e.target.value); setHasChanges(true) }}
                 placeholder={apiKeys[provider]?.has_key ? 'Enter new key to replace...' : 'Enter API key...'}
               />
+              {(['moonshot', 'minimax'] as string[]).includes(provider) && (
+                <p style={{ fontSize: '0.78rem', color: 'var(--text-muted, #888)', marginTop: 6, lineHeight: 1.4 }}>
+                  {apiKeys['openrouter']?.has_key
+                    ? 'OpenRouter is configured and will be used automatically if the direct API is unavailable in your region.'
+                    : 'This provider may be geo-restricted. If the direct API fails, configure OpenRouter as a fallback — it will be used automatically.'}
+                </p>
+              )}
             </div>
           )}
 
+          {/* OpenRouter credits */}
+          {provider === 'openrouter' && currentProvider?.supports_catalog && (
+            <OpenRouterCreditsBanner
+              send={send}
+              onMessage={onMessage}
+              isConnected={isConnected}
+              hasApiKey={!!apiKeys[provider]?.has_key}
+            />
+          )}
+
           {/* Base URL */}
           {currentProvider?.base_url_env && (
             <div className={styles.formGroup}>
@@ -781,7 +844,17 @@ export function ModelSettings() {
                   </span>
                 )
               ) : (
-                testResult.error || testResult.message
+                <span style={{ textAlign: 'center', display: 'block' }}>
+                  <span>{testResult.error || testResult.message}</span>
+                  {(['moonshot', 'minimax'] as string[]).includes(provider) && (
+                    <span style={{ marginTop: 12, display: 'block', fontSize: '0.82rem', color: 'var(--text-muted, #888)', lineHeight: 1.5 }}>
+                      This provider may be geo-restricted in your region.
+                      {apiKeys['openrouter']?.has_key
+                        ? ' OpenRouter is already configured and will be used as a fallback automatically.'
+                        : ' Configure OpenRouter in Settings → select "OpenRouter" provider — it will be used as a fallback automatically.'}
+                    </span>
+                  )}
+                </span>
               )}
             </p>
             <Button variant="secondary" onClick={() => { setTestResult(null); setTestBeforeSave(false) }}>
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx b/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx
new file mode 100644
index 00000000..0decda58
--- /dev/null
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/OpenRouterModelPicker.tsx
@@ -0,0 +1,474 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Loader2, RefreshCw, Eye, Wrench, Database, ExternalLink } from 'lucide-react'
+import styles from './SettingsPage.module.css'
+
+export interface OpenRouterModel {
+  id: string
+  canonical_slug: string | null
+  name: string
+  description: string
+  context_length: number | null
+  input_modalities: string[]
+  output_modalities: string[]
+  pricing: {
+    prompt: string | null
+    completion: string | null
+    image: string | null
+    input_cache_read: string | null
+    input_cache_write: string | null
+  }
+  supported_parameters: string[]
+  is_moderated: boolean | null
+}
+
+export interface OpenRouterCredits {
+  balance: number | null
+  usage: number
+  limit: number | null
+  label: string | null
+  is_free_tier: boolean | null
+}
+
+type WsSend = (type: string, data?: Record<string, unknown>) => void
+type WsOnMessage = (type: string, handler: (data: unknown) => void) => () => void
+
+// ─────────────────────────────────────────────────────────────────────
+// Hooks: catalog and credits
+// ─────────────────────────────────────────────────────────────────────
+
+export function useOpenRouterCatalog(
+  send: WsSend,
+  onMessage: WsOnMessage,
+  isConnected: boolean,
+  enabled: boolean,
+  baseUrl?: string,
+) {
+  const [models, setModels] = useState<OpenRouterModel[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [fetchedAt, setFetchedAt] = useState<number | null>(null)
+  const requestedRef = useRef(false)
+  const prevBaseUrlRef = useRef(baseUrl)
+
+  useEffect(() => {
+    const cleanup = onMessage('openrouter_models_get', (data: unknown) => {
+      const d = data as { success: boolean; models?: OpenRouterModel[]; error?: string; fetched_at?: number }
+      setLoading(false)
+      if (d.success && d.models) {
+        setModels(d.models)
+        setError(null)
+        if (d.fetched_at) setFetchedAt(d.fetched_at)
+      } else {
+        setError(d.error || 'Failed to load models')
+      }
+    })
+    return cleanup
+  }, [onMessage])
+
+  // Fetch once after we go enabled+connected. Re-fetch when baseUrl changes.
+  useEffect(() => {
+    // Reset the guard when baseUrl changes so the new endpoint is fetched.
+    if (prevBaseUrlRef.current !== baseUrl) {
+      prevBaseUrlRef.current = baseUrl
+      requestedRef.current = false
+    }
+    if (!isConnected || !enabled || requestedRef.current) return
+    requestedRef.current = true
+    setLoading(true)
+    setError(null)
+    send('openrouter_models_get', baseUrl ? { baseUrl } : {})
+  }, [isConnected, enabled, baseUrl, send])
+
+  const refresh = () => {
+    setLoading(true)
+    setError(null)
+    send('openrouter_models_get', { ...(baseUrl ? { baseUrl } : {}), forceRefresh: true })
+  }
+
+  return { models, loading, error, fetchedAt, refresh }
+}
+
+export function useOpenRouterCredits(
+  send: WsSend,
+  onMessage: WsOnMessage,
+  isConnected: boolean,
+  hasApiKey: boolean,
+) {
+  const [credits, setCredits] = useState<OpenRouterCredits | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const cleanup = onMessage('openrouter_credits_get', (data: unknown) => {
+      const d = data as {
+        success: boolean
+        balance?: number | null
+        usage?: number
+        limit?: number | null
+        label?: string | null
+        is_free_tier?: boolean | null
+        error?: string
+      }
+      setLoading(false)
+      if (d.success) {
+        setCredits({
+          balance: d.balance ?? null,
+          usage: d.usage ?? 0,
+          limit: d.limit ?? null,
+          label: d.label ?? null,
+          is_free_tier: d.is_free_tier ?? null,
+        })
+        setError(null)
+      } else {
+        setCredits(null)
+        setError(d.error || 'Failed to load credits')
+      }
+    })
+    return cleanup
+  }, [onMessage])
+
+  useEffect(() => {
+    if (!isConnected || !hasApiKey) {
+      setCredits(null)
+      return
+    }
+    setLoading(true)
+    send('openrouter_credits_get')
+  }, [isConnected, hasApiKey, send])
+
+  return { credits, loading, error }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────
+
+function formatPricePerMillion(p: string | null | undefined): string | null {
+  if (p == null) return null
+  const n = parseFloat(p)
+  if (isNaN(n)) return null
+  if (n === 0) return null
+  const perM = n * 1_000_000
+  if (perM >= 100) return `$${perM.toFixed(0)}`
+  if (perM >= 1) return `$${perM.toFixed(2)}`
+  if (perM >= 0.01) return `$${perM.toFixed(3)}`
+  return `$${perM.toFixed(4)}`
+}
+
+function isFreeModel(m: OpenRouterModel): boolean {
+  if (m.id.endsWith(':free')) return true
+  const p = parseFloat(m.pricing.prompt || '0')
+  const c = parseFloat(m.pricing.completion || '0')
+  return (isNaN(p) || p === 0) && (isNaN(c) || c === 0)
+}
+
+function supportsVision(m: OpenRouterModel): boolean {
+  return m.input_modalities.includes('image')
+}
+
+function supportsTools(m: OpenRouterModel): boolean {
+  return m.supported_parameters.includes('tools') || m.supported_parameters.includes('tool_choice')
+}
+
+function supportsCache(m: OpenRouterModel): boolean {
+  return Boolean(m.pricing.input_cache_read)
+}
+
+function upstreamOf(id: string): string {
+  const slash = id.indexOf('/')
+  return slash > 0 ? id.slice(0, slash) : id
+}
+
+function formatContext(n: number | null | undefined): string {
+  if (n == null) return ''
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`
+  if (n >= 1_000) return `${Math.round(n / 1_000)}K`
+  return `${n}`
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Credits banner
+// ─────────────────────────────────────────────────────────────────────
+
+interface CreditsBannerProps {
+  send: WsSend
+  onMessage: WsOnMessage
+  isConnected: boolean
+  hasApiKey: boolean
+}
+
+export function OpenRouterCreditsBanner({ send, onMessage, isConnected, hasApiKey }: CreditsBannerProps) {
+  const { credits, loading, error } = useOpenRouterCredits(send, onMessage, isConnected, hasApiKey)
+
+  if (!hasApiKey) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>
+          Save an API key to see credit balance.
+        </span>
+        <a
+          className={styles.orCreditsLink}
+          href="https://openrouter.ai/keys"
+          target="_blank"
+          rel="noreferrer"
+        >
+          Get a key <ExternalLink size={12} />
+        </a>
+      </div>
+    )
+  }
+
+  if (loading) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>
+          <Loader2 size={12} className={styles.spinning} /> Loading credits…
+        </span>
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className={styles.orCreditsRow}>
+        <span className={styles.orCreditsLabel}>Credits: {error}</span>
+      </div>
+    )
+  }
+
+  if (!credits) return null
+
+  const balanceText = credits.balance != null
+    ? `$${credits.balance.toFixed(2)} remaining`
+    : 'Pay-as-you-go (no preset limit)'
+
+  return (
+    <div className={styles.orCreditsRow}>
+      <span className={styles.orCreditsLabel}>
+        Credits: <strong>{balanceText}</strong>
+        {credits.label ? <span className={styles.orCreditsKey}> · {credits.label}</span> : null}
+      </span>
+      <a
+        className={styles.orCreditsLink}
+        href="https://openrouter.ai/credits"
+        target="_blank"
+        rel="noreferrer"
+      >
+        Top up <ExternalLink size={12} />
+      </a>
+    </div>
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Model picker
+// ─────────────────────────────────────────────────────────────────────
+
+interface PickerProps {
+  models: OpenRouterModel[]
+  loading: boolean
+  error: string | null
+  value: string
+  onChange: (v: string) => void
+  onRefresh: () => void
+  requireVision?: boolean
+  label: string
+}
+
+export function OpenRouterModelPicker({
+  models,
+  loading,
+  error,
+  value,
+  onChange,
+  onRefresh,
+  requireVision = false,
+  label,
+}: PickerProps) {
+  const [search, setSearch] = useState('')
+  const [filterFree, setFilterFree] = useState(false)
+  const [filterVision, setFilterVision] = useState(requireVision)
+  const [filterTools, setFilterTools] = useState(false)
+  const [filterCache, setFilterCache] = useState(false)
+  const [upstream, setUpstream] = useState<string>('')
+
+  // VLM picker should keep the vision filter pinned on
+  useEffect(() => {
+    if (requireVision) setFilterVision(true)
+  }, [requireVision])
+
+  const upstreams = useMemo(() => {
+    const set = new Set<string>()
+    for (const m of models) set.add(upstreamOf(m.id))
+    return Array.from(set).sort()
+  }, [models])
+
+  const filtered = useMemo(() => {
+    const q = search.trim().toLowerCase()
+    return models.filter(m => {
+      if (filterFree && !isFreeModel(m)) return false
+      if (filterVision && !supportsVision(m)) return false
+      if (filterTools && !supportsTools(m)) return false
+      if (filterCache && !supportsCache(m)) return false
+      if (upstream && upstreamOf(m.id) !== upstream) return false
+      if (!q) return true
+      return (
+        m.id.toLowerCase().includes(q) ||
+        m.name.toLowerCase().includes(q) ||
+        (m.description || '').toLowerCase().includes(q)
+      )
+    })
+  }, [models, search, filterFree, filterVision, filterTools, filterCache, upstream])
+
+  return (
+    <div className={styles.formGroup}>
+      <label>{label}</label>
+
+      <div className={styles.orPicker}>
+        <div className={styles.orPickerHeader}>
+          <input
+            type="text"
+            className={styles.searchInput}
+            placeholder={`Search ${models.length || ''} models...`}
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+          />
+          <button
+            type="button"
+            className={styles.orPickerRefreshBtn}
+            onClick={onRefresh}
+            title="Refresh catalog"
+            disabled={loading}
+          >
+            {loading ? <Loader2 size={14} className={styles.spinning} /> : <RefreshCw size={14} />}
+          </button>
+        </div>
+
+        <div className={styles.orPickerFilters}>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterFree ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterFree(v => !v)}
+            aria-pressed={filterFree}
+          >
+            Free only
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterVision ? styles.orPickerChipActive : ''}`}
+            onClick={() => !requireVision && setFilterVision(v => !v)}
+            aria-pressed={filterVision}
+            disabled={requireVision}
+            title={requireVision ? 'Vision required for VLM models' : undefined}
+          >
+            Vision
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterTools ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterTools(v => !v)}
+            aria-pressed={filterTools}
+          >
+            Tools
+          </button>
+          <button
+            type="button"
+            className={`${styles.orPickerChip} ${filterCache ? styles.orPickerChipActive : ''}`}
+            onClick={() => setFilterCache(v => !v)}
+            aria-pressed={filterCache}
+          >
+            Caching
+          </button>
+          <select
+            className={styles.orPickerUpstream}
+            value={upstream}
+            onChange={(e) => setUpstream(e.target.value)}
+          >
+            <option value="">Any upstream</option>
+            {upstreams.map(u => (
+              <option key={u} value={u}>{u}</option>
+            ))}
+          </select>
+        </div>
+
+        <div className={styles.orPickerList}>
+          {loading && models.length === 0 && (
+            <div className={styles.orPickerStatus}>
+              <Loader2 size={14} className={styles.spinning} /> Loading catalog…
+            </div>
+          )}
+          {error && (
+            <div className={styles.orPickerError}>
+              {error}
+              <button type="button" onClick={onRefresh}>Retry</button>
+            </div>
+          )}
+          {!loading && !error && filtered.length === 0 && (
+            <div className={styles.orPickerStatus}>
+              No models match your filters.
+            </div>
+          )}
+          {filtered.map(m => {
+            const free = isFreeModel(m)
+            const promptPrice = formatPricePerMillion(m.pricing.prompt)
+            const completionPrice = formatPricePerMillion(m.pricing.completion)
+            const ctxStr = formatContext(m.context_length)
+            const selected = value === m.id
+            return (
+              <button
+                key={m.id}
+                type="button"
+                className={`${styles.orPickerRow} ${selected ? styles.orPickerRowSelected : ''}`}
+                onClick={() => onChange(m.id)}
+              >
+                <div className={styles.orPickerRowLeft}>
+                  <div className={styles.orPickerRowName}>{m.name}</div>
+                  <div className={styles.orPickerRowSlug}>{m.id}</div>
+                </div>
+                <div className={styles.orPickerRowRight}>
+                  <div className={styles.orPickerRowMeta}>
+                    {ctxStr && <span className={styles.orPickerCtx}>{ctxStr} ctx</span>}
+                    {supportsVision(m) && (
+                      <span className={styles.orPickerCap} title="Vision capable">
+                        <Eye size={12} />
+                      </span>
+                    )}
+                    {supportsTools(m) && (
+                      <span className={styles.orPickerCap} title="Tool calling">
+                        <Wrench size={12} />
+                      </span>
+                    )}
+                    {supportsCache(m) && (
+                      <span className={styles.orPickerCap} title="Prompt caching">
+                        <Database size={12} />
+                      </span>
+                    )}
+                  </div>
+                  <div className={styles.orPickerRowPrice}>
+                    {free ? (
+                      <span className={styles.orPickerFreeBadge}>FREE</span>
+                    ) : promptPrice && completionPrice ? (
+                      <span>In {promptPrice} · Out {completionPrice} <span className={styles.orPickerPriceUnit}>/M</span></span>
+                    ) : (
+                      <span className={styles.orPickerPriceUnit}>see openrouter.ai</span>
+                    )}
+                  </div>
+                </div>
+              </button>
+            )
+          })}
+        </div>
+
+        <div className={styles.orPickerSlug}>
+          <label>Or paste a slug:</label>
+          <input
+            type="text"
+            value={value}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder="anthropic/claude-sonnet-4.5"
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
index 0666da24..68e5c57c 100644
--- a/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Settings/SettingsPage.module.css
@@ -603,6 +603,65 @@
   line-height: 1.5;
 }
 
+/* Compact danger row — for low-risk maintenance actions */
+.dangerRowList {
+  display: flex;
+  flex-direction: column;
+}
+
+.dangerRow {
+  display: grid;
+  grid-template-columns: 18px 1fr auto;
+  align-items: center;
+  column-gap: var(--space-3);
+  padding: var(--space-3) 0;
+}
+
+.dangerRow:first-child {
+  padding-top: var(--space-1);
+}
+
+.dangerRow:last-child {
+  padding-bottom: var(--space-1);
+}
+
+.dangerRow + .dangerRow {
+  border-top: 1px solid rgba(239, 68, 68, 0.15);
+}
+
+.dangerRowIcon {
+  align-self: start;
+  margin-top: 2px;
+  color: var(--color-red);
+}
+
+.dangerRowInfo {
+  min-width: 0;
+}
+
+.dangerRowTitle {
+  font-size: var(--text-sm);
+  font-weight: var(--font-semibold);
+  color: var(--color-red);
+  margin: 0 0 2px 0;
+  line-height: 1.2;
+}
+
+.dangerRowHint {
+  font-size: var(--text-xs);
+  color: var(--text-secondary);
+  margin: 0;
+  line-height: 1.4;
+}
+
+.dangerRowAction {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--space-2);
+  min-width: 96px;
+}
+
 /* Status Messages */
 .statusSuccess {
   display: inline-flex;
@@ -2161,3 +2220,310 @@
   margin: 0;
   background: transparent;
 }
+
+/* ─────────────────────────────────────────────────────────────────────
+   OpenRouter model picker + credits banner
+   Used only when provider === 'openrouter'.
+   ───────────────────────────────────────────────────────────────────── */
+
+/* Credits row — label-style, not an input. Mirrors the muted-text look
+   used elsewhere in settings (see .hint at line 183). No background, no
+   border — just a row of text with a trailing link. */
+.orCreditsRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  padding: 0 var(--space-1);
+  font-size: var(--text-xs);
+  color: var(--text-secondary);
+  margin: calc(-1 * var(--space-2)) 0 var(--space-1);
+}
+
+.orCreditsLabel {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.orCreditsLabel strong {
+  color: var(--text-primary);
+  font-weight: 500;
+}
+
+.orCreditsKey {
+  color: var(--text-muted);
+}
+
+.orCreditsLink {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--color-primary);
+  text-decoration: none;
+}
+
+.orCreditsLink:hover {
+  text-decoration: underline;
+}
+
+.orPicker {
+  border: 1px solid var(--border-primary);
+  border-radius: var(--radius-md);
+  background: var(--bg-secondary);
+  display: flex;
+  flex-direction: column;
+}
+
+/* Header reuses the shared .searchInput control (see line 1543) so the
+   style is consistent with Skills/MCP/Integrations search bars. */
+.orPickerHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-2) var(--space-3);
+  border-bottom: 1px solid var(--border-primary);
+}
+
+.orPickerHeader .searchInput {
+  flex: 1;
+}
+
+.orPickerRefreshBtn {
+  background: transparent;
+  border: 1px solid var(--border-primary);
+  color: var(--text-secondary);
+  border-radius: var(--radius-sm);
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+
+.orPickerRefreshBtn:hover {
+  background: var(--bg-tertiary);
+}
+
+.orPickerRefreshBtn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.orPickerFilters {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border-primary);
+  font-size: 12px;
+  color: var(--text-secondary);
+}
+
+/* Filter chips behave as toggle-buttons. Visual language mirrors the
+   shared .toggle switch (line 245): gray surface when off, primary
+   when on — so the on/off semantics match the rest of settings. */
+.orPickerChip {
+  display: inline-flex;
+  align-items: center;
+  padding: 4px 10px;
+  border-radius: var(--radius-full);
+  border: 1px solid var(--border-primary);
+  background: transparent;
+  color: var(--text-secondary);
+  font-size: var(--text-xs);
+  cursor: pointer;
+  user-select: none;
+  transition: background var(--transition-fast), color var(--transition-fast), border-color var(--transition-fast);
+}
+
+.orPickerChip:hover:not(:disabled) {
+  background: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.orPickerChip:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.orPickerChipActive {
+  background: var(--color-primary);
+  border-color: var(--color-primary);
+  color: var(--color-white);
+}
+
+.orPickerChipActive:hover:not(:disabled) {
+  background: var(--color-primary);
+  color: var(--color-white);
+}
+
+.orPickerUpstream {
+  margin-left: auto;
+  padding: 3px 6px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-primary);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 12px;
+}
+
+.orPickerList {
+  max-height: 360px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.orPickerStatus {
+  padding: 16px;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--text-secondary);
+  font-size: 13px;
+}
+
+.orPickerError {
+  padding: 12px 14px;
+  color: var(--color-warning);
+  font-size: 13px;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.orPickerError button {
+  background: transparent;
+  color: var(--color-primary);
+  border: 1px solid var(--border-primary);
+  padding: 3px 10px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+}
+
+.orPickerRow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px 12px;
+  border: none;
+  border-bottom: 1px solid var(--border-primary);
+  background: transparent;
+  text-align: left;
+  cursor: pointer;
+  color: var(--text-primary);
+  width: 100%;
+}
+
+.orPickerRow:last-child {
+  border-bottom: none;
+}
+
+.orPickerRow:hover {
+  background: var(--bg-tertiary);
+}
+
+.orPickerRowSelected {
+  background: var(--color-primary-light);
+  border-left: 3px solid var(--color-primary);
+  padding-left: 9px;
+}
+
+.orPickerRowLeft {
+  flex: 1;
+  min-width: 0;
+}
+
+.orPickerRowName {
+  font-size: 13px;
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.orPickerRowSlug {
+  font-size: 11px;
+  color: var(--text-tertiary);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.orPickerRowRight {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: 4px;
+  flex-shrink: 0;
+  min-width: 160px;
+  text-align: right;
+}
+
+.orPickerRowMeta {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--text-tertiary);
+  font-size: 11px;
+}
+
+.orPickerCtx {
+  font-variant-numeric: tabular-nums;
+}
+
+.orPickerCap {
+  display: inline-flex;
+  align-items: center;
+  color: var(--text-secondary);
+}
+
+.orPickerRowPrice {
+  font-size: 11px;
+  color: var(--text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+.orPickerPriceUnit {
+  color: var(--text-tertiary);
+}
+
+.orPickerFreeBadge {
+  background: var(--color-success-light);
+  color: var(--color-success);
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+}
+
+.orPickerSlug {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--border-primary);
+}
+
+.orPickerSlug label {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  margin: 0;
+  white-space: nowrap;
+}
+
+.orPickerSlug input {
+  flex: 1;
+  padding: 6px 10px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border-primary);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  font-size: 12px;
+  font-family: var(--font-mono);
+}
diff --git a/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.module.css b/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.module.css
index 10f8f49e..bee66330 100644
--- a/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.module.css
+++ b/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.module.css
@@ -202,6 +202,7 @@
   gap: var(--space-2);
 }
 
+
 .cancelButton {
   display: flex;
   align-items: center;
@@ -328,6 +329,63 @@
   color: var(--color-primary-hover);
 }
 
+/* ─────────────────────────────────────────────────────────────────────
+   Todo List Display (task_update_todos action)
+   ───────────────────────────────────────────────────────────────────── */
+
+.todoItems {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.todoItem {
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-2);
+  padding: var(--space-1) 0;
+  background: transparent;
+  font-size: var(--text-sm);
+  color: var(--text-primary);
+  line-height: var(--leading-normal);
+}
+
+.todoIcon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  margin-top: 2px;
+  color: var(--text-muted);
+}
+
+.todoContent {
+  flex: 1;
+  word-break: break-word;
+  white-space: pre-wrap;
+}
+
+.todoCompleted .todoIcon {
+  color: var(--text-muted);
+}
+
+.todoCompleted .todoContent {
+  text-decoration: line-through;
+  color: var(--text-muted);
+}
+
+.todoInProgress .todoIcon {
+  color: var(--color-primary);
+}
+
+.todoInProgress .todoContent {
+  font-weight: var(--font-medium);
+  color: var(--text-primary);
+}
+
 /* Reasoning item - minimal styling, no icon */
 .reasoningItem {
   color: var(--text-muted);
diff --git a/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.tsx b/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.tsx
index c023afdf..d5c7938b 100644
--- a/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.tsx
+++ b/app/ui_layer/browser/frontend/src/pages/Tasks/TasksPage.tsx
@@ -1,11 +1,24 @@
 import React, { useState, useRef, useEffect, useCallback, useMemo } from 'react'
-import { ChevronRight, XCircle, ArrowLeft, Reply } from 'lucide-react'
+import { ChevronRight, XCircle, ArrowLeft, Reply, Plus, Square, CheckSquare } from 'lucide-react'
 import { useNavigate } from 'react-router-dom'
 import { useWebSocket } from '../../contexts/WebSocketContext'
-import { StatusIndicator, Badge, Button, IconButton } from '../../components/ui'
+import { StatusIndicator, Badge, Button, IconButton, SkillCreatorModal } from '../../components/ui'
 import type { ActionItem } from '../../types'
+import { useSkillCreator } from './useSkillCreator'
 import styles from './TasksPage.module.css'
 
+function isInternalWorkflowTask(
+  item: ActionItem,
+  internalWorkflowIds: Set<string>,
+  internalSkillNames: Set<string>,
+): boolean {
+  if (item.workflowId && internalWorkflowIds.has(item.workflowId)) return true
+  for (const s of item.selectedSkills ?? []) {
+    if (internalSkillNames.has(s)) return true
+  }
+  return false
+}
+
 // Expandable value component for long text
 const MAX_VALUE_LENGTH = 80
 
@@ -266,16 +279,117 @@ function JsonDisplay({ content }: { content: string }) {
   )
 }
 
+// ─────────────────────────────────────────────────────────────────────
+// Todo List Display (for task_update_todos action)
+// ─────────────────────────────────────────────────────────────────────
+
+type TodoStatus = 'pending' | 'in_progress' | 'completed' | string
+
+interface TodoEntry {
+  content: string
+  status: TodoStatus
+}
+
+function extractTodos(content: string): TodoEntry[] | null {
+  // First try the standard parser
+  const parsed = parsePythonDict(content)
+  const raw = (parsed as Record<string, unknown>)?.todos
+
+  // The parsePythonDict helper currently stores arrays as the raw "[...]"
+  // string slice, so try to recover real objects either from a real array
+  // or by parsing the array string as JSON / a small Python-literal subset.
+  let items: unknown[] | null = null
+
+  if (Array.isArray(raw)) {
+    items = raw
+  } else if (typeof raw === 'string') {
+    items = tryParseArrayLiteral(raw)
+  }
+
+  if (!items) return null
+
+  const todos: TodoEntry[] = []
+  for (const item of items) {
+    if (item && typeof item === 'object') {
+      const obj = item as Record<string, unknown>
+      const todoContent = obj.content
+      const status = obj.status
+      if (typeof todoContent === 'string' && typeof status === 'string') {
+        todos.push({ content: todoContent, status })
+      }
+    }
+  }
+
+  return todos.length > 0 ? todos : null
+}
+
+function tryParseArrayLiteral(raw: string): unknown[] | null {
+  // Direct JSON
+  try {
+    const parsed = JSON.parse(raw)
+    if (Array.isArray(parsed)) return parsed
+  } catch {
+    // fall through
+  }
+
+  // Python-style array: single quotes + True/False/None — convert to JSON
+  try {
+    let normalized = raw.trim()
+    // Replace Python literals with JSON equivalents (only when whole-word)
+    normalized = normalized
+      .replace(/\bTrue\b/g, 'true')
+      .replace(/\bFalse\b/g, 'false')
+      .replace(/\bNone\b/g, 'null')
+    // Naive single-quote → double-quote swap. Good enough for our schema
+    // (todo content/status are plain words/sentences without embedded quotes
+    // most of the time); fall back to null on failure.
+    normalized = normalized.replace(/'/g, '"')
+    const parsed = JSON.parse(normalized)
+    if (Array.isArray(parsed)) return parsed
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+function TodoListDisplay({ todos }: { todos: TodoEntry[] }) {
+  return (
+    <ul className={styles.todoItems}>
+      {todos.map((todo, index) => {
+        const isCompleted = todo.status === 'completed'
+        const isInProgress = todo.status === 'in_progress'
+        const itemClass = [
+          styles.todoItem,
+          isCompleted ? styles.todoCompleted : '',
+          isInProgress ? styles.todoInProgress : '',
+        ].filter(Boolean).join(' ')
+        return (
+          <li key={index} className={itemClass}>
+            <span className={styles.todoIcon} aria-hidden="true">
+              {isCompleted ? <CheckSquare size={16} /> : <Square size={16} />}
+            </span>
+            <span className={styles.todoContent}>{todo.content}</span>
+          </li>
+        )
+      })}
+    </ul>
+  )
+}
+
 // Panel width limits (1:3 ratio default)
 const DEFAULT_PANEL_WIDTH = 350
 const MIN_PANEL_WIDTH = 200
 const MAX_PANEL_WIDTH = 600
 
 export function TasksPage() {
-  const { actions, messages, cancelTask, cancellingTaskId, setReplyTarget, loadOlderActions, hasMoreActions, loadingOlderActions } = useWebSocket()
+  const { actions, messages, cancelTask, cancellingTaskId, setReplyTarget, loadOlderActions, hasMoreActions, loadingOlderActions, skillMeta } = useWebSocket()
+  const internalWorkflowIds = useMemo(() => new Set(skillMeta.internalWorkflowIds), [skillMeta.internalWorkflowIds])
+  const internalSkillNames = useMemo(() => new Set(skillMeta.internalSkillNames), [skillMeta.internalSkillNames])
+  const reservedSkillNames = useMemo(() => new Set(skillMeta.reservedSkillNames), [skillMeta.reservedSkillNames])
   const navigate = useNavigate()
   const [selectedItem, setSelectedItem] = useState<ActionItem | null>(null)
   const [mobileShowDetail, setMobileShowDetail] = useState(false)
+  const skillCreator = useSkillCreator()
 
   // Resizable panel state
   const [panelWidth, setPanelWidth] = useState(DEFAULT_PANEL_WIDTH)
@@ -510,6 +624,15 @@ export function TasksPage() {
                     >
                       {cancellingTaskId === selectedItem.id ? 'Cancelling...' : 'Cancel Task'}
                     </Button>
+                  ) : selectedItem.status === 'completed' && !isInternalWorkflowTask(selectedItem, internalWorkflowIds, internalSkillNames) ? (
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      icon={<Plus size={14} />}
+                      onClick={() => skillCreator.open(selectedItem)}
+                    >
+                      Create Skill
+                    </Button>
                   ) : (selectedItem.status === 'error' || selectedItem.status === 'cancelled') && (
                     <Badge variant="error">Aborted</Badge>
                   )}
@@ -535,6 +658,24 @@ export function TasksPage() {
                   <dd>{formatTimestamp(selectedItem.createdAt)}</dd>
                   <dt>Duration</dt>
                   <dd>{formatDuration(selectedItem.duration)}</dd>
+                  {selectedItem.itemType === 'task' && selectedItem.inputTokens != null && (
+                    <>
+                      <dt>Input Tokens</dt>
+                      <dd>{selectedItem.inputTokens.toLocaleString()}</dd>
+                    </>
+                  )}
+                  {selectedItem.itemType === 'task' && selectedItem.outputTokens != null && (
+                    <>
+                      <dt>Output Tokens</dt>
+                      <dd>{selectedItem.outputTokens.toLocaleString()}</dd>
+                    </>
+                  )}
+                  {selectedItem.itemType === 'task' && selectedItem.cacheTokens != null && (
+                    <>
+                      <dt>Cache Tokens</dt>
+                      <dd>{selectedItem.cacheTokens.toLocaleString()}</dd>
+                    </>
+                  )}
                 </dl>
               </div>
 
@@ -549,12 +690,23 @@ export function TasksPage() {
                 )
               ) : (
                 <>
-                  {selectedItem.input && (
-                    <div className={styles.detailSection}>
-                      <h4>Input</h4>
-                      <JsonDisplay content={selectedItem.input} />
-                    </div>
-                  )}
+                  {selectedItem.input && (() => {
+                    const normalizedName = (selectedItem.name || '')
+                      .toLowerCase()
+                      .replace(/[\s-]+/g, '_')
+                    const isTodoAction =
+                      selectedItem.itemType === 'action' &&
+                      normalizedName === 'task_update_todos'
+                    const todos = isTodoAction ? extractTodos(selectedItem.input) : null
+                    return (
+                      <div className={styles.detailSection}>
+                        <h4>{todos ? 'Todos' : 'Input'}</h4>
+                        {todos
+                          ? <TodoListDisplay todos={todos} />
+                          : <JsonDisplay content={selectedItem.input} />}
+                      </div>
+                    )
+                  })()}
 
                   {selectedItem.output && (
                     <div className={styles.detailSection}>
@@ -581,6 +733,17 @@ export function TasksPage() {
           </div>
         )}
       </div>
+
+      <SkillCreatorModal
+        isOpen={skillCreator.isOpen}
+        sourceSkills={skillCreator.sourceSkills}
+        reservedNames={reservedSkillNames}
+        status={skillCreator.status}
+        serverError={skillCreator.serverError}
+        successInfo={skillCreator.successInfo}
+        onClose={skillCreator.close}
+        onSubmit={skillCreator.submit}
+      />
     </div>
   )
 }
diff --git a/app/ui_layer/browser/frontend/src/pages/Tasks/useSkillCreator.ts b/app/ui_layer/browser/frontend/src/pages/Tasks/useSkillCreator.ts
new file mode 100644
index 00000000..799fc61b
--- /dev/null
+++ b/app/ui_layer/browser/frontend/src/pages/Tasks/useSkillCreator.ts
@@ -0,0 +1,124 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useSettingsWebSocket } from '../Settings/useSettingsWebSocket'
+import type { ActionItem } from '../../types'
+import type { SkillCreatorSubmit, SkillCreatorSuccessInfo } from '../../components/ui/SkillCreatorModal'
+
+export type SkillCreatorStatus = 'idle' | 'submitting' | 'success' | 'error'
+
+interface SkillCreatorResponse {
+  success: boolean
+  taskId?: string
+  skillName?: string
+  mode?: 'create' | 'improve'
+  error?: string
+}
+
+const ERROR_MESSAGES: Record<string, string> = {
+  invalid_mode: 'Invalid request mode.',
+  missing_task_id: 'No source task selected.',
+  missing_skill_name: 'Enter a skill name.',
+  invalid_skill_name: 'Skill name format is invalid.',
+  reserved_skill_name: 'That name is reserved.',
+  source_task_not_found: 'Source task no longer exists.',
+  source_task_not_completed: 'Source task is not completed.',
+  source_task_is_internal_workflow: 'This task cannot be turned into a skill.',
+  skill_already_exists: 'A skill with this name already exists.',
+  skill_not_found: 'The target skill no longer exists.',
+  workflow_busy: 'Another skill workflow is in progress. Try again in a moment.',
+  task_manager_unavailable: 'Agent is not ready.',
+  workflow_lock_unavailable: 'Agent is not ready.',
+}
+
+function humanize(error: string | undefined): string {
+  if (!error) return 'Unknown error.'
+  return ERROR_MESSAGES[error] ?? error
+}
+
+export function useSkillCreator() {
+  const { send, onMessage } = useSettingsWebSocket()
+  const [isOpen, setIsOpen] = useState(false)
+  const [sourceTask, setSourceTask] = useState<ActionItem | null>(null)
+  const [status, setStatus] = useState<SkillCreatorStatus>('idle')
+  const [serverError, setServerError] = useState<string | null>(null)
+  const [lastResult, setLastResult] = useState<SkillCreatorResponse | null>(null)
+
+  // Subscribe to backend responses. The modal stays OPEN on success so the
+  // user sees the "submitted, agent is working" confirmation inside the
+  // dialog they were just interacting with — they dismiss it manually with
+  // the Close button. (Previously the modal auto-closed and a tiny chip in
+  // the top bar showed status, which was confusing.)
+  useEffect(() => {
+    const unsubscribe = onMessage('create_skill_from_task', (data: unknown) => {
+      const resp = data as SkillCreatorResponse
+      setLastResult(resp)
+      if (resp.success) {
+        setStatus('success')
+        setServerError(null)
+      } else {
+        setStatus('error')
+        setServerError(humanize(resp.error))
+      }
+    })
+    return unsubscribe
+  }, [onMessage])
+
+  const open = useCallback((task: ActionItem) => {
+    setSourceTask(task)
+    setIsOpen(true)
+    setServerError(null)
+    setStatus('idle')
+  }, [])
+
+  const close = useCallback(() => {
+    if (status === 'submitting') return // don't allow closing mid-flight
+    setIsOpen(false)
+    setSourceTask(null)
+    setServerError(null)
+    // Reset status so the next open shows a fresh form (otherwise a prior
+    // success/error would persist and the modal would skip the form view).
+    setStatus('idle')
+    setLastResult(null)
+  }, [status])
+
+  const submit = useCallback((payload: SkillCreatorSubmit) => {
+    if (!sourceTask) return
+    setStatus('submitting')
+    setServerError(null)
+    send('create_skill_from_task', {
+      taskId: sourceTask.id,
+      mode: payload.mode,
+      skillName: payload.skillName,
+      targetSkill: payload.targetSkill,
+    })
+  }, [send, sourceTask])
+
+  // Stabilize the array reference — `?? []` would yield a new array each
+  // render, which invalidates downstream useMemo/useEffect deps in the modal
+  // and causes the form to reset on every parent re-render (e.g. while
+  // submitting).
+  const sourceSkills = useMemo(
+    () => sourceTask?.selectedSkills ?? [],
+    [sourceTask],
+  )
+
+  // Compact view of the last successful submit, for the modal's success
+  // state. Returns null unless we have a valid skill name + mode pair.
+  const successInfo = useMemo<SkillCreatorSuccessInfo | null>(() => {
+    if (status !== 'success') return null
+    if (!lastResult?.skillName || !lastResult?.mode) return null
+    return { skillName: lastResult.skillName, mode: lastResult.mode }
+  }, [status, lastResult])
+
+  return {
+    isOpen,
+    sourceTask,
+    sourceSkills,
+    status,
+    serverError,
+    lastResult,
+    successInfo,
+    open,
+    close,
+    submit,
+  }
+}
diff --git a/app/ui_layer/browser/frontend/src/types/index.ts b/app/ui_layer/browser/frontend/src/types/index.ts
index 25c4dfcb..a355b29e 100644
--- a/app/ui_layer/browser/frontend/src/types/index.ts
+++ b/app/ui_layer/browser/frontend/src/types/index.ts
@@ -50,6 +50,11 @@ export interface ActionItem {
   output?: string
   error?: string
   duration?: number
+  selectedSkills?: string[]
+  workflowId?: string
+  inputTokens?: number
+  outputTokens?: number
+  cacheTokens?: number
 }
 
 // ─────────────────────────────────────────────────────────────────────
@@ -105,6 +110,9 @@ export type WSMessageType =
   // Task control
   | 'task_cancel'
   | 'task_cancel_response'
+  // Skill creation from completed task
+  | 'create_skill_from_task'
+  | 'skill_meta'
   // Option click (interactive buttons in chat)
   | 'option_click'
   // Onboarding
@@ -141,6 +149,7 @@ export type WSMessageType =
   | 'living_ui_stop'
   | 'living_ui_delete'
   | 'living_ui_state_update'
+  | 'living_ui_data_changed'
   | 'living_ui_error'
 
 export interface WSMessage {
@@ -161,6 +170,12 @@ export interface InitialState {
   agentName?: string
 }
 
+export interface SkillMeta {
+  internalWorkflowIds: string[]
+  internalSkillNames: string[]
+  reservedSkillNames: string[]
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // Dashboard Types
 // ─────────────────────────────────────────────────────────────────────
diff --git a/app/ui_layer/commands/builtin/__init__.py b/app/ui_layer/commands/builtin/__init__.py
index 75a79eed..08f7eb79 100644
--- a/app/ui_layer/commands/builtin/__init__.py
+++ b/app/ui_layer/commands/builtin/__init__.py
@@ -2,6 +2,7 @@
 
 from app.ui_layer.commands.builtin.help import HelpCommand
 from app.ui_layer.commands.builtin.clear import ClearCommand
+from app.ui_layer.commands.builtin.clear_tasks import ClearTasksCommand
 from app.ui_layer.commands.builtin.reset import ResetCommand
 from app.ui_layer.commands.builtin.exit import ExitCommand
 from app.ui_layer.commands.builtin.menu import MenuCommand
@@ -17,6 +18,7 @@
 __all__ = [
     "HelpCommand",
     "ClearCommand",
+    "ClearTasksCommand",
     "ResetCommand",
     "ExitCommand",
     "MenuCommand",
diff --git a/app/ui_layer/commands/builtin/clear_tasks.py b/app/ui_layer/commands/builtin/clear_tasks.py
new file mode 100644
index 00000000..1a49b51b
--- /dev/null
+++ b/app/ui_layer/commands/builtin/clear_tasks.py
@@ -0,0 +1,58 @@
+"""Clear-tasks command implementation."""
+
+from __future__ import annotations
+
+from typing import List
+
+from app.ui_layer.commands.base import Command, CommandResult
+
+
+class ClearTasksCommand(Command):
+    """Clear finished tasks (completed/failed/aborted) from the action panel."""
+
+    @property
+    def name(self) -> str:
+        return "/clear-tasks"
+
+    @property
+    def aliases(self) -> List[str]:
+        return ["/cleartasks"]
+
+    @property
+    def description(self) -> str:
+        return "Remove completed, failed, and aborted tasks from the panel"
+
+    @property
+    def help_text(self) -> str:
+        return (
+            "Remove tasks whose status is completed, error, or cancelled "
+            "(failed/aborted) from the action panel, along with their child "
+            "actions. Running and waiting tasks are preserved.\n\n"
+            "Dashboard usage data and task history are not affected."
+        )
+
+    async def execute(
+        self,
+        args: List[str],
+        adapter_id: str = "",
+    ) -> CommandResult:
+        """Execute the clear-tasks command."""
+        adapter = self._controller.active_adapter
+        if not adapter or not adapter.action_panel:
+            self.emit_message(
+                "No action panel is available in this interface.",
+                "error",
+            )
+            return CommandResult(success=False)
+
+        removed = await adapter.action_panel.clear_terminal_tasks()
+
+        if removed:
+            self.emit_message(
+                f"Cleared {removed} finished task{'s' if removed != 1 else ''} from the panel.",
+                "system",
+            )
+        else:
+            self.emit_message("No finished tasks to clear.", "system")
+
+        return CommandResult(success=True)
diff --git a/app/ui_layer/commands/builtin/cred.py b/app/ui_layer/commands/builtin/cred.py
index d9809136..e3098163 100644
--- a/app/ui_layer/commands/builtin/cred.py
+++ b/app/ui_layer/commands/builtin/cred.py
@@ -5,7 +5,11 @@
 from typing import List
 
 from app.ui_layer.commands.base import Command, CommandResult
-from app.credentials.handlers import INTEGRATION_HANDLERS
+from craftos_integrations import (
+    get_all_handlers,
+    is_connected,
+    parse_status_accounts,
+)
 
 
 class CredCommand(Command):
@@ -35,7 +39,7 @@ def help_text(self) -> str:
 Use /<integration> commands to manage specific integrations:
   /google       - Google integration
   /slack        - Slack integration
-  /telegram     - Telegram integration
+  /telegram_bot - Telegram Bot integration
   etc.
 
 Examples:
@@ -74,40 +78,40 @@ async def _list_credentials(self) -> CommandResult:
         """List all configured credentials."""
         lines = ["Configured credentials:", ""]
 
-        for name, handler in INTEGRATION_HANDLERS.items():
-            try:
-                status = handler.get_status() if hasattr(handler, "get_status") else {}
-                connected = status.get("connected", False)
-                status_text = "connected" if connected else "not connected"
-                lines.append(f"  {name}: {status_text}")
-            except Exception:
-                lines.append(f"  {name}: unknown")
+        for name in get_all_handlers():
+            connected = is_connected(name)
+            lines.append(f"  {name}: {'connected' if connected else 'not connected'}")
 
         return CommandResult(success=True, message="\n".join(lines))
 
     async def _show_status(self) -> CommandResult:
-        """Show integration status."""
+        """Show integration status with per-account info when connected."""
         lines = ["Integration status:", ""]
 
         connected_count = 0
-        total_count = len(INTEGRATION_HANDLERS)
+        all_handlers = get_all_handlers()
 
-        for name, handler in INTEGRATION_HANDLERS.items():
+        for name, handler in all_handlers.items():
+            display = handler.display_name or name
             try:
-                status = handler.get_status() if hasattr(handler, "get_status") else {}
-                connected = status.get("connected", False)
+                _, status_msg = await handler.status()
+                first = status_msg.split("\n", 1)[0]
+                connected = "Connected" in first and "Not connected" not in first
                 if connected:
                     connected_count += 1
-                    account = status.get("account", "")
-                    account_info = f" ({account})" if account else ""
-                    lines.append(f"  [+] {name}{account_info}")
+                    accounts = parse_status_accounts(status_msg)
+                    if accounts:
+                        account_label = ", ".join(a.get("display") or a.get("id", "") for a in accounts)
+                        lines.append(f"  [+] {display} ({account_label})")
+                    else:
+                        lines.append(f"  [+] {display}")
                 else:
-                    lines.append(f"  [ ] {name}")
+                    lines.append(f"  [ ] {display}")
             except Exception:
-                lines.append(f"  [?] {name}")
+                lines.append(f"  [?] {display}")
 
         lines.append("")
-        lines.append(f"{connected_count}/{total_count} integrations connected")
+        lines.append(f"{connected_count}/{len(all_handlers)} integrations connected")
         lines.append("")
         lines.append("Use /<integration> to manage a specific integration.")
 
@@ -117,11 +121,11 @@ async def _list_integrations(self) -> CommandResult:
         """List available integrations."""
         lines = ["Available integrations:", ""]
 
-        for name, handler in INTEGRATION_HANDLERS.items():
-            desc = ""
-            if hasattr(handler, "description"):
-                desc = f" - {handler.description}"
-            lines.append(f"  /{name}{desc}")
+        for name, handler in get_all_handlers().items():
+            display = handler.display_name or name
+            description = handler.description
+            suffix = f" — {description}" if description else ""
+            lines.append(f"  /{name}  ({display}){suffix}")
 
         lines.append("")
         lines.append("Use /<integration> to see commands for that integration.")
diff --git a/app/ui_layer/commands/builtin/integrations.py b/app/ui_layer/commands/builtin/integrations.py
index b924da95..2a8eb75b 100644
--- a/app/ui_layer/commands/builtin/integrations.py
+++ b/app/ui_layer/commands/builtin/integrations.py
@@ -1,7 +1,7 @@
 """Integration-specific command implementation.
 
-All connect / disconnect / status operations go through the centralised
-``integration_settings`` module so that terminal, browser, and agent
+All connect / disconnect / status operations go through the
+``craftos_integrations`` package so that terminal, browser, and agent
 share the same logic and side-effects (e.g. platform-listener startup).
 """
 
@@ -10,16 +10,17 @@
 from typing import List
 
 from app.ui_layer.commands.base import Command, CommandResult
-from app.external_comms.integration_settings import (
-    INTEGRATION_REGISTRY,
-    get_integration_info,
+from craftos_integrations import (
+    connect_token as connect_integration_token,
+    connect_oauth as connect_integration_oauth,
+    connect_interactive as connect_integration_interactive,
+    disconnect as _disconnect_integration,
+    get_handler,
     get_integration_auth_type,
-    connect_integration_token,
-    connect_integration_oauth,
-    connect_integration_interactive,
-    disconnect_integration as _disconnect_integration,
+    get_integration_fields,
+    get_integration_info_sync as get_integration_info,
+    get_metadata,
 )
-from app.credentials.handlers import INTEGRATION_HANDLERS
 
 
 class IntegrationCommand(Command):
@@ -28,7 +29,6 @@ class IntegrationCommand(Command):
     def __init__(self, controller, integration_name: str) -> None:
         super().__init__(controller)
         self._integration_name = integration_name
-        self._handler = INTEGRATION_HANDLERS.get(integration_name)
 
     @property
     def name(self) -> str:
@@ -36,9 +36,9 @@ def name(self) -> str:
 
     @property
     def description(self) -> str:
-        info = INTEGRATION_REGISTRY.get(self._integration_name)
-        if info:
-            return f"{info['name']} — {info['description']}"
+        meta = get_metadata(self._integration_name)
+        if meta:
+            return f"{meta['name']} — {meta['description']}"
         return f"Manage {self._integration_name} integration"
 
     @property
@@ -48,21 +48,21 @@ def usage(self) -> str:
     @property
     def help_text(self) -> str:
         lines = [f"Manage {self._integration_name} integration.", ""]
-
-        if self._handler:
-            if hasattr(self._handler, "get_commands"):
-                commands = self._handler.get_commands()
-                if commands:
-                    lines.append("Commands:")
-                    for cmd_name, cmd_desc in commands.items():
-                        lines.append(f"  {cmd_name} - {cmd_desc}")
-                    lines.append("")
-
         lines.append("Common commands:")
         lines.append("  connect    - Connect to integration")
         lines.append("  disconnect - Disconnect from integration")
         lines.append("  status     - Show connection status")
 
+        # Surface handler-specific subcommands (login-qr, invite, etc.)
+        handler = get_handler(self._integration_name)
+        if handler:
+            extras = [s for s in getattr(handler, "subcommands", []) if s not in {"login", "logout", "status"}]
+            if extras:
+                lines.append("")
+                lines.append("Integration-specific subcommands:")
+                for sub in extras:
+                    lines.append(f"  {sub}")
+
         return "\n".join(lines)
 
     async def execute(
@@ -70,7 +70,7 @@ async def execute(
         args: List[str],
         adapter_id: str = "",
     ) -> CommandResult:
-        if self._integration_name not in INTEGRATION_REGISTRY:
+        if get_metadata(self._integration_name) is None:
             return CommandResult(
                 success=False,
                 message=f"Integration not available: {self._integration_name}",
@@ -90,9 +90,10 @@ async def execute(
             return await self._disconnect()
 
         # Delegate handler-specific subcommands (login-qr, invite, etc.)
-        if self._handler:
+        handler = get_handler(self._integration_name)
+        if handler:
             try:
-                success, message = await self._handler.handle(subcommand, sub_args)
+                success, message = await handler.handle(subcommand, sub_args)
                 return CommandResult(success=success, message=message)
             except Exception as e:
                 return CommandResult(success=False, message=f"Command error: {e}")
@@ -103,7 +104,7 @@ async def execute(
         )
 
     async def _show_status(self) -> CommandResult:
-        """Show integration status via the centralised integration_settings module."""
+        """Show integration status (metadata + live connection state)."""
         try:
             info = get_integration_info(self._integration_name)
             if not info:
@@ -125,15 +126,14 @@ async def _show_status(self) -> CommandResult:
             return CommandResult(success=False, message=f"Failed to get status: {e}")
 
     async def _connect(self, args: List[str]) -> CommandResult:
-        """Connect via the centralised integration_settings module.
+        """Dispatch to the right craftos_integrations connect_* helper.
 
-        Determines the correct auth flow (token / oauth / interactive)
-        based on the integration's auth_type and the arguments provided.
+        Picks the auth path (token / oauth / interactive) from the handler's
+        declared ``auth_type``.
         """
         try:
             auth_type = get_integration_auth_type(self._integration_name)
-            info = INTEGRATION_REGISTRY.get(self._integration_name, {})
-            fields = info.get("fields", [])
+            fields = get_integration_fields(self._integration_name)
 
             # Token-based: args should provide credential values in field order
             if auth_type in ("token", "both", "token_with_interactive") and (args or fields):
@@ -174,7 +174,6 @@ async def _connect(self, args: List[str]) -> CommandResult:
             return CommandResult(success=False, message=f"Connection failed: {e}")
 
     async def _disconnect(self) -> CommandResult:
-        """Disconnect via the centralised integration_settings module."""
         try:
             success, message = await _disconnect_integration(self._integration_name)
             return CommandResult(success=success, message=message)
diff --git a/app/ui_layer/commands/builtin/provider.py b/app/ui_layer/commands/builtin/provider.py
index e9c1d9b7..4008b660 100644
--- a/app/ui_layer/commands/builtin/provider.py
+++ b/app/ui_layer/commands/builtin/provider.py
@@ -19,6 +19,7 @@ class ProviderCommand(Command):
         "byteplus": ("BYTEPLUS_API_KEY", "BytePlus"),
         "deepseek": ("DEEPSEEK_API_KEY", "DeepSeek"),
         "grok": ("XAI_API_KEY", "Grok (xAI)"),
+        "openrouter": ("OPENROUTER_API_KEY", "OpenRouter"),
         "remote": (None, "Ollama (Local)"),
     }
 
@@ -48,12 +49,16 @@ def help_text(self) -> str:
   gemini     - Google Gemini models
   anthropic  - Anthropic Claude models
   byteplus   - BytePlus Kimi models
+  deepseek   - DeepSeek models
+  grok       - Grok (xAI) models
+  openrouter - OpenRouter (300+ models, one key)
   remote     - Ollama (local models)
 
 Examples:
   /provider
   /provider openai
-  /provider openai sk-xxx"""
+  /provider openai sk-xxx
+  /provider openrouter sk-or-v1-xxx"""
 
     async def execute(
         self,
diff --git a/app/ui_layer/components/protocols.py b/app/ui_layer/components/protocols.py
index cb608fbd..a2278226 100644
--- a/app/ui_layer/components/protocols.py
+++ b/app/ui_layer/components/protocols.py
@@ -112,6 +112,28 @@ async def update_item_data(
         """
         ...
 
+    async def update_item_tokens(
+        self,
+        item_id: str,
+        input_tokens: int,
+        output_tokens: int,
+        cache_tokens: int,
+    ) -> None:
+        """
+        Update a task item's cumulative LLM token usage counters.
+
+        Called per-LLM-call to push the running totals (input, output, cache)
+        to the UI so the user sees them tick up while the task runs and
+        frozen at the final value when it completes.
+
+        Args:
+            item_id: ID of the task item to update
+            input_tokens: Cumulative input tokens for this task
+            output_tokens: Cumulative output tokens for this task
+            cache_tokens: Cumulative cache tokens for this task (read+creation)
+        """
+        ...
+
     async def remove_item(self, item_id: str) -> None:
         """
         Remove an item from the panel.
@@ -125,6 +147,16 @@ async def clear(self) -> None:
         """Clear all items from the panel."""
         ...
 
+    async def clear_terminal_tasks(self) -> int:
+        """
+        Remove tasks whose status is completed/error/cancelled, along with
+        their child actions. Running/waiting tasks are preserved.
+
+        Returns:
+            Number of items removed.
+        """
+        ...
+
     def select_task(self, task_id: Optional[str]) -> None:
         """
         Select a task for detail view.
diff --git a/app/ui_layer/components/types.py b/app/ui_layer/components/types.py
index c3dd373f..85fa9c9b 100644
--- a/app/ui_layer/components/types.py
+++ b/app/ui_layer/components/types.py
@@ -101,6 +101,8 @@ class ActionItem:
         input_data: Input parameters/schema for the action
         output_data: Output/result of the action
         error_message: Error message if action failed
+        selected_skills: Skills attached to the task (task-level only)
+        workflow_id: Internal workflow this task belongs to (task-level only)
     """
 
     id: str
@@ -113,6 +115,11 @@ class ActionItem:
     input_data: Optional[str] = None
     output_data: Optional[str] = None
     error_message: Optional[str] = None
+    selected_skills: List[str] = field(default_factory=list)
+    workflow_id: Optional[str] = None
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cache_tokens: Optional[int] = None
 
     @property
     def is_task(self) -> bool:
diff --git a/app/ui_layer/controller/ui_controller.py b/app/ui_layer/controller/ui_controller.py
index d06e9729..cace2291 100644
--- a/app/ui_layer/controller/ui_controller.py
+++ b/app/ui_layer/controller/ui_controller.py
@@ -109,6 +109,15 @@ def __init__(
         # Register enabled skills as slash commands
         self._register_skill_commands()
 
+        # Expose the event bus on global STATE so module-level hooks
+        # (e.g. _report_usage in app/llm/interface.py) can emit UI events
+        # without needing a controller handle.
+        try:
+            from app.state.agent_state import STATE
+            STATE.event_bus = self._event_bus
+        except Exception:
+            pass
+
     # ─────────────────────────────────────────────────────────────────────
     # Properties
     # ─────────────────────────────────────────────────────────────────────
@@ -540,6 +549,7 @@ def _register_builtin_commands(self) -> None:
         from app.ui_layer.commands.builtin import (
             HelpCommand,
             ClearCommand,
+            ClearTasksCommand,
             ResetCommand,
             ExitCommand,
             MenuCommand,
@@ -552,6 +562,7 @@ def _register_builtin_commands(self) -> None:
 
         self._command_registry.register(HelpCommand(self))
         self._command_registry.register(ClearCommand(self))
+        self._command_registry.register(ClearTasksCommand(self))
         self._command_registry.register(ResetCommand(self))
         self._command_registry.register(ExitCommand(self))
         self._command_registry.register(MenuCommand(self))
@@ -565,11 +576,16 @@ def _register_builtin_commands(self) -> None:
         self._register_integration_commands()
 
     def _register_integration_commands(self) -> None:
-        """Register integration-specific commands."""
-        from app.credentials.handlers import INTEGRATION_HANDLERS
+        """Register integration-specific commands.
+
+        ``manager.start()`` (called during agent step 6) has already populated
+        the registry by the time the UI controller boots, so we just iterate
+        the registered handler names.
+        """
+        from craftos_integrations import get_registered_handler_names
         from app.ui_layer.commands.builtin.integrations import IntegrationCommand
 
-        for integration_name in INTEGRATION_HANDLERS:
+        for integration_name in get_registered_handler_names():
             cmd = IntegrationCommand(self, integration_name)
             self._command_registry.register(cmd)
 
diff --git a/app/ui_layer/events/event_types.py b/app/ui_layer/events/event_types.py
index e00d175f..0ca6bd4e 100644
--- a/app/ui_layer/events/event_types.py
+++ b/app/ui_layer/events/event_types.py
@@ -23,6 +23,7 @@ class UIEventType(Enum):
     TASK_START = auto()
     TASK_END = auto()
     TASK_UPDATE = auto()
+    TASK_TOKEN_UPDATE = auto()
     ACTION_START = auto()
     ACTION_END = auto()
     ACTION_UPDATE = auto()
diff --git a/app/ui_layer/metrics/collector.py b/app/ui_layer/metrics/collector.py
index 3f9ee0f6..c9a6e03e 100644
--- a/app/ui_layer/metrics/collector.py
+++ b/app/ui_layer/metrics/collector.py
@@ -946,7 +946,7 @@ def get_metrics(self) -> DashboardMetrics:
             # Task metrics
             total_tasks = len(self._task_records)
             completed_count = len([t for t in self._task_records if t.status == "completed"])
-            failed_count = len([t for t in self._task_records if t.status == "error"])
+            failed_count = len([t for t in self._task_records if t.status in ("error", "cancelled")])
             running_count = len(self._running_tasks)
 
             finished_tasks = completed_count + failed_count
diff --git a/app/ui_layer/onboarding/controller.py b/app/ui_layer/onboarding/controller.py
index 04b6631f..5f77d7dc 100644
--- a/app/ui_layer/onboarding/controller.py
+++ b/app/ui_layer/onboarding/controller.py
@@ -244,7 +244,16 @@ def _complete(self) -> None:
 
         # Extract collected data
         provider = self._state.collected_data.get("provider", "openai")
-        api_key = self._state.collected_data.get("api_key", "")
+        raw_api_key_value = self._state.collected_data.get("api_key", "")
+        # Proxied providers (moonshot/minimax) submit {api_key, via, or_model?}
+        if isinstance(raw_api_key_value, dict):
+            api_key = raw_api_key_value.get("api_key", "")
+            submitted_or_model = raw_api_key_value.get("or_model", "")
+            proxied_via = raw_api_key_value.get("via", "openrouter")
+        else:
+            api_key = raw_api_key_value
+            submitted_or_model = ""
+            proxied_via = "direct"
         agent_name_data = self._state.collected_data.get("agent_name", "Agent")
         # Agent name step is a form step, so the collected value is a dict.
         # Accept plain strings too for backward compatibility.
@@ -256,11 +265,29 @@ def _complete(self) -> None:
         selected_skills = self._state.collected_data.get("skills", [])
 
         # Save provider configuration to settings.json
+        from app.onboarding.interfaces.steps import ApiKeyStep
         if provider == "remote":
             # api_key holds the Ollama base URL for the remote provider
             remote_url = api_key or "http://localhost:11434"
             from app.tui.settings import save_remote_endpoint
             save_remote_endpoint(remote_url)
+        elif provider in ApiKeyStep.OPENROUTER_PROXIED and api_key:
+            if proxied_via == "openrouter":
+                # User chose to go via OpenRouter — save key as openrouter and set model slug.
+                if submitted_or_model:
+                    or_model = submitted_or_model
+                else:
+                    from agent_core.core.models.factory import _to_openrouter_slug, _OR_MODEL_MAP
+                    from app.models import MODEL_REGISTRY, InterfaceType
+                    native_model = MODEL_REGISTRY.get(provider, {}).get(InterfaceType.LLM, "")
+                    or_model = _OR_MODEL_MAP.get(provider, {}).get(native_model) or _to_openrouter_slug(provider, native_model)
+                save_settings_to_json("openrouter", api_key)
+                from app.ui_layer.settings.model_settings import update_model_settings
+                update_model_settings(llm_model=or_model, vlm_model=or_model)
+                provider = "openrouter"
+            else:
+                # User has direct access — save key under the native provider.
+                save_settings_to_json(provider, api_key)
         elif provider and api_key:
             save_settings_to_json(provider, api_key)
 
diff --git a/app/ui_layer/settings/__init__.py b/app/ui_layer/settings/__init__.py
index e20e5fb5..16149a17 100644
--- a/app/ui_layer/settings/__init__.py
+++ b/app/ui_layer/settings/__init__.py
@@ -32,20 +32,21 @@
     remove_skill,
 )
 
-from app.external_comms.integration_settings import (
-    list_integrations,
-    get_integration_info,
+from craftos_integrations import (
+    connect_token as connect_integration_token,
+    connect_oauth as connect_integration_oauth,
+    connect_interactive as connect_integration_interactive,
+    disconnect as disconnect_integration,
     get_integration_accounts,
-    connect_integration_token,
-    connect_integration_oauth,
-    connect_integration_interactive,
-    disconnect_integration,
     get_integration_auth_type,
     get_integration_fields,
-    # WhatsApp QR code flow
-    start_whatsapp_qr_session,
-    check_whatsapp_session_status,
-    cancel_whatsapp_session,
+    get_integration_info_sync as get_integration_info,
+    list_integrations_sync as list_integrations,
+)
+from craftos_integrations.integrations.whatsapp_web import (
+    start_qr_session as start_whatsapp_qr_session,
+    check_qr_session_status as check_whatsapp_session_status,
+    cancel_qr_session as cancel_whatsapp_session,
 )
 
 # General settings
diff --git a/app/ui_layer/settings/living_ui_settings.py b/app/ui_layer/settings/living_ui_settings.py
index 71d2fa04..9170a8e4 100644
--- a/app/ui_layer/settings/living_ui_settings.py
+++ b/app/ui_layer/settings/living_ui_settings.py
@@ -38,42 +38,6 @@ def get_living_ui_projects() -> Dict[str, Any]:
         return {"success": False, "error": str(e), "projects": []}
 
 
-async def living_ui_project_action(project_id: str, action: str) -> Dict[str, Any]:
-    """Execute an action on a Living UI project.
-
-    Args:
-        project_id: The project ID
-        action: One of 'launch', 'stop', 'delete'
-
-    Returns:
-        Dict with 'success' and optional 'error'
-    """
-    try:
-        from app.living_ui import get_living_ui_manager
-
-        manager = get_living_ui_manager()
-        if not manager:
-            return {"success": False, "error": "Living UI manager not initialized"}
-
-        project = manager.get_project(project_id)
-        if not project:
-            return {"success": False, "error": f"Project not found: {project_id}"}
-
-        if action == 'launch':
-            success = await manager.launch_project(project_id)
-            return {"success": success, "error": None if success else "Launch failed"}
-        elif action == 'stop':
-            success = await manager.stop_project(project_id)
-            return {"success": success}
-        elif action == 'delete':
-            success = await manager.delete_project(project_id)
-            return {"success": success}
-        else:
-            return {"success": False, "error": f"Unknown action: {action}"}
-    except Exception as e:
-        return {"success": False, "error": str(e)}
-
-
 def update_project_setting(project_id: str, setting: str, value: Any) -> Dict[str, Any]:
     """Update a per-project setting.
 
diff --git a/app/ui_layer/settings/model_settings.py b/app/ui_layer/settings/model_settings.py
index 9e3b7c52..4f4ed32e 100644
--- a/app/ui_layer/settings/model_settings.py
+++ b/app/ui_layer/settings/model_settings.py
@@ -51,30 +51,43 @@
         "settings_key": "byteplus",
         "requires_api_key": True,
     },
-    # "minimax": {
-    #     "name": "MiniMax",
-    #     "api_key_env": "MINIMAX_API_KEY",
-    #     "settings_key": "minimax",
-    #     "requires_api_key": True,
-    # },
+    "minimax": {
+        "name": "MiniMax",
+        "api_key_env": "MINIMAX_API_KEY",
+        "settings_key": "minimax",
+        "requires_api_key": True,
+    },
     "deepseek": {
         "name": "DeepSeek",
         "api_key_env": "DEEPSEEK_API_KEY",
         "settings_key": "deepseek",
         "requires_api_key": True,
     },
-    # "moonshot": {
-    #     "name": "Moonshot",
-    #     "api_key_env": "MOONSHOT_API_KEY",
-    #     "settings_key": "moonshot",
-    #     "requires_api_key": True,
-    # },
+    "moonshot": {
+        "name": "Moonshot",
+        "api_key_env": "MOONSHOT_API_KEY",
+        "settings_key": "moonshot",
+        "requires_api_key": True,
+    },
     "grok": {
         "name": "Grok (xAI)",
         "api_key_env": "XAI_API_KEY",
         "settings_key": "grok",
         "requires_api_key": True,
     },
+    "openrouter": {
+        "name": "OpenRouter",
+        "api_key_env": "OPENROUTER_API_KEY",
+        # Intentionally no base_url_env — the OpenRouter endpoint is fixed for
+        # almost everyone, and exposing the field confused users into thinking
+        # they had to fill it in. Power users who need a custom gateway can
+        # still set endpoints.openrouter_base_url in settings.json by hand;
+        # the backend still reads it (see app/config.py get_base_url).
+        "settings_key": "openrouter",
+        "requires_api_key": True,
+        # Frontend opts in to a catalog-aware picker for this provider.
+        "supports_catalog": True,
+    },
     "remote": {
         "name": "Local (Ollama)",
         "base_url_env": "REMOTE_MODEL_URL",
@@ -162,6 +175,7 @@ def get_available_providers() -> Dict[str, Any]:
                 "llm_model": llm_model,
                 "vlm_model": vlm_model,
                 "has_vlm": vlm_model is not None,
+                "supports_catalog": info.get("supports_catalog", False),
             })
 
         return {
@@ -229,6 +243,9 @@ def get_model_settings() -> Dict[str, Any]:
         if remote_url:
             base_urls["remote"] = remote_url
 
+        if endpoints_settings.get("openrouter_base_url"):
+            base_urls["openrouter"] = endpoints_settings["openrouter_base_url"]
+
         return {
             "success": True,
             "llm_provider": llm_provider,
@@ -323,6 +340,8 @@ def update_model_settings(
                 settings["endpoints"]["byteplus_base_url"] = base_url
             elif provider_for_url == "remote":
                 settings["endpoints"]["remote_model_url"] = base_url
+            elif provider_for_url == "openrouter":
+                settings["endpoints"]["openrouter_base_url"] = base_url
 
         # Clear remote URL when switching away from remote so stale values don't persist
         if llm_provider and llm_provider != "remote" and old_llm_provider == "remote" and not provider_for_url:
@@ -353,6 +372,7 @@ def test_connection(
     provider: str,
     api_key: Optional[str] = None,
     base_url: Optional[str] = None,
+    model: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Test connection to a provider.
 
@@ -360,6 +380,10 @@ def test_connection(
         provider: Provider to test
         api_key: Optional API key to test with (if not provided, uses stored key)
         base_url: Optional base URL for byteplus/remote providers
+        model: Optional model id to verify. When provided the tester does a
+            tiny chat completion against this exact model so a typo in the
+            model id is caught at test time, not at first real call. When
+            omitted, falls back to a known-good test model (auth check only).
 
     Returns:
         Dict with test results
@@ -378,17 +402,20 @@ def test_connection(
                 api_key = api_keys_settings.get(settings_key)
 
         # If no base URL provided, try to get it from settings.json
-        if base_url is None and provider in ["byteplus", "remote"]:
+        if base_url is None and provider in ["byteplus", "remote", "openrouter"]:
             if provider == "byteplus":
                 base_url = endpoints_settings.get("byteplus_base_url")
             elif provider == "remote":
                 base_url = endpoints_settings.get("remote_model_url")
+            elif provider == "openrouter":
+                base_url = endpoints_settings.get("openrouter_base_url")
 
         # Run connection test
         result = test_provider_connection(
             provider=provider,
             api_key=api_key,
             base_url=base_url,
+            model=model,
         )
 
         return result
diff --git a/app/ui_layer/settings/openrouter_catalog.py b/app/ui_layer/settings/openrouter_catalog.py
new file mode 100644
index 00000000..18724a9f
--- /dev/null
+++ b/app/ui_layer/settings/openrouter_catalog.py
@@ -0,0 +1,225 @@
+"""OpenRouter catalog + credits helpers for the settings UI.
+
+OpenRouter exposes a public model catalog at GET /api/v1/models (no auth)
+and a credits endpoint at GET /api/v1/credits / GET /api/v1/auth/key
+(auth required). The model picker renders the catalog and the balance.
+
+The catalog is cached in-process for 5 minutes — OpenRouter publishes new
+models periodically, but ~300 entries is enough payload that we don't
+want to re-fetch on every settings page open.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from app.config import get_api_key, get_base_url
+
+
+_DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+_CATALOG_TTL_SECONDS = 300  # 5 min — matches OR's own cache windows
+_CATALOG_TIMEOUT = 15.0
+_CREDITS_TIMEOUT = 10.0
+
+# In-process cache: { base_url: (timestamp, models) }
+_catalog_cache: Dict[str, tuple] = {}
+
+
+def _resolve_base_url(base_url: Optional[str] = None) -> str:
+    if base_url:
+        return base_url
+    configured = get_base_url("openrouter")
+    return configured or _DEFAULT_BASE_URL
+
+
+def _normalize_model(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """Project the OpenRouter model record to the fields the UI needs.
+
+    OpenRouter's payload is large per-model (descriptions, hugging-face links,
+    etc.). We only ship what the picker actually renders — keeps WS frames
+    small and makes the frontend types narrower.
+    """
+    pricing = raw.get("pricing") or {}
+    architecture = raw.get("architecture") or {}
+    top_provider = raw.get("top_provider") or {}
+    return {
+        "id": raw.get("id"),
+        "canonical_slug": raw.get("canonical_slug"),
+        "name": raw.get("name") or raw.get("id"),
+        "description": (raw.get("description") or "")[:500],
+        "context_length": raw.get("context_length") or top_provider.get("context_length"),
+        "input_modalities": architecture.get("input_modalities") or [],
+        "output_modalities": architecture.get("output_modalities") or [],
+        "pricing": {
+            "prompt": pricing.get("prompt"),
+            "completion": pricing.get("completion"),
+            "image": pricing.get("image"),
+            "input_cache_read": pricing.get("input_cache_read"),
+            "input_cache_write": pricing.get("input_cache_write"),
+        },
+        "supported_parameters": raw.get("supported_parameters") or [],
+        "is_moderated": top_provider.get("is_moderated"),
+    }
+
+
+def fetch_models(
+    base_url: Optional[str] = None,
+    *,
+    force_refresh: bool = False,
+) -> Dict[str, Any]:
+    """Return the OpenRouter model catalog (cached).
+
+    Returns:
+        {"success": bool, "models": [...], "fetched_at": int, "error": str?}
+    """
+    url = _resolve_base_url(base_url)
+    cache_key = url
+
+    if not force_refresh:
+        entry = _catalog_cache.get(cache_key)
+        if entry is not None:
+            ts, models = entry
+            if (time.time() - ts) < _CATALOG_TTL_SECONDS:
+                return {
+                    "success": True,
+                    "models": models,
+                    "fetched_at": int(ts),
+                    "cached": True,
+                }
+
+    try:
+        with httpx.Client(timeout=_CATALOG_TIMEOUT) as client:
+            response = client.get(f"{url.rstrip('/')}/models")
+        if response.status_code != 200:
+            return {
+                "success": False,
+                "models": [],
+                "error": f"OpenRouter /models returned status {response.status_code}",
+            }
+        raw_models = response.json().get("data") or []
+        models = [_normalize_model(m) for m in raw_models if m.get("id")]
+        _catalog_cache[cache_key] = (time.time(), models)
+        return {
+            "success": True,
+            "models": models,
+            "fetched_at": int(time.time()),
+            "cached": False,
+        }
+    except httpx.TimeoutException:
+        return {
+            "success": False,
+            "models": [],
+            "error": "Timed out fetching OpenRouter model catalog",
+        }
+    except httpx.RequestError as exc:
+        return {
+            "success": False,
+            "models": [],
+            "error": f"Network error fetching OpenRouter models: {exc}",
+        }
+    except Exception as exc:  # pragma: no cover — defensive
+        return {
+            "success": False,
+            "models": [],
+            "error": f"Unexpected error fetching OpenRouter models: {exc}",
+        }
+
+
+def fetch_credits(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Return account credit info for the configured OpenRouter key.
+
+    Hits /api/v1/credits (preferred — newer endpoint with `total_credits` /
+    `total_usage`). Falls back to /api/v1/auth/key on 404 since older keys /
+    routes still expose the legacy shape.
+
+    Returns:
+        {"success": bool, "balance": float, "usage": float, "limit": float?,
+         "label": str?, "error": str?}
+    """
+    if not api_key:
+        api_key = get_api_key("openrouter")
+    if not api_key:
+        return {
+            "success": False,
+            "error": "No OpenRouter API key configured",
+        }
+
+    url = _resolve_base_url(base_url)
+    headers = {"Authorization": f"Bearer {api_key}"}
+
+    try:
+        with httpx.Client(timeout=_CREDITS_TIMEOUT) as client:
+            response = client.get(f"{url.rstrip('/')}/credits", headers=headers)
+            if response.status_code == 404:
+                # Legacy fallback
+                response = client.get(f"{url.rstrip('/')}/auth/key", headers=headers)
+
+        if response.status_code in (401, 403):
+            return {
+                "success": False,
+                "error": "Invalid API key",
+            }
+        if response.status_code != 200:
+            return {
+                "success": False,
+                "error": f"Credits endpoint returned status {response.status_code}",
+            }
+
+        data = response.json().get("data") or {}
+
+        # /credits shape: { total_credits, total_usage }
+        # /auth/key shape: { label, usage, limit, is_free_tier, ... }
+        total_credits = data.get("total_credits")
+        total_usage = data.get("total_usage")
+        if total_credits is not None or total_usage is not None:
+            credits = float(total_credits) if total_credits is not None else 0.0
+            usage = float(total_usage) if total_usage is not None else 0.0
+            return {
+                "success": True,
+                "balance": max(0.0, credits - usage),
+                "usage": usage,
+                "limit": credits if total_credits is not None else None,
+                "label": data.get("label"),
+                "is_free_tier": data.get("is_free_tier"),
+            }
+
+        # Legacy /auth/key
+        usage = float(data.get("usage") or 0.0)
+        limit = data.get("limit")
+        balance = None
+        if limit is not None:
+            balance = max(0.0, float(limit) - usage)
+        return {
+            "success": True,
+            "balance": balance,
+            "usage": usage,
+            "limit": float(limit) if limit is not None else None,
+            "label": data.get("label"),
+            "is_free_tier": data.get("is_free_tier"),
+        }
+
+    except httpx.TimeoutException:
+        return {
+            "success": False,
+            "error": "Timed out fetching OpenRouter credits",
+        }
+    except httpx.RequestError as exc:
+        return {
+            "success": False,
+            "error": f"Network error fetching OpenRouter credits: {exc}",
+        }
+    except Exception as exc:  # pragma: no cover — defensive
+        return {
+            "success": False,
+            "error": f"Unexpected error fetching OpenRouter credits: {exc}",
+        }
+
+
+def invalidate_catalog_cache() -> None:
+    _catalog_cache.clear()
diff --git a/app/usage/action_storage.py b/app/usage/action_storage.py
index 1c41c154..21bc3c65 100644
--- a/app/usage/action_storage.py
+++ b/app/usage/action_storage.py
@@ -8,9 +8,10 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import sqlite3
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -21,6 +22,17 @@
     logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
 
 
+def _decode_skills(value: Optional[str]) -> List[str]:
+    """Decode the JSON-encoded selected_skills column. Tolerates legacy NULL/garbage."""
+    if not value:
+        return []
+    try:
+        decoded = json.loads(value)
+        return decoded if isinstance(decoded, list) else []
+    except (ValueError, TypeError):
+        return []
+
+
 @dataclass
 class StoredActionItem:
     """An action item stored in the database."""
@@ -35,6 +47,13 @@ class StoredActionItem:
     input_data: Optional[str] = None
     output_data: Optional[str] = None
     error_message: Optional[str] = None
+    # Task-level metadata (populated only when item_type == "task")
+    selected_skills: List[str] = field(default_factory=list)
+    workflow_id: Optional[str] = None
+    # Per-task cumulative LLM token usage (task-level only; None for actions)
+    input_tokens: Optional[int] = None
+    output_tokens: Optional[int] = None
+    cache_tokens: Optional[int] = None
 
     @property
     def duration(self) -> Optional[int]:
@@ -56,6 +75,11 @@ def to_dict(self) -> Dict[str, Any]:
             "input": self.input_data,
             "output": self.output_data,
             "error": self.error_message,
+            "selectedSkills": self.selected_skills,
+            "workflowId": self.workflow_id,
+            "inputTokens": self.input_tokens,
+            "outputTokens": self.output_tokens,
+            "cacheTokens": self.cache_tokens,
         }
 
 
@@ -101,10 +125,26 @@ def _init_db(self) -> None:
                     input_data TEXT,
                     output_data TEXT,
                     error_message TEXT,
+                    selected_skills TEXT,
+                    workflow_id TEXT,
                     db_created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
                 )
             """)
 
+            # Idempotent column add for pre-existing DBs
+            cursor.execute("PRAGMA table_info(action_items)")
+            existing_columns = {row[1] for row in cursor.fetchall()}
+            if "selected_skills" not in existing_columns:
+                cursor.execute("ALTER TABLE action_items ADD COLUMN selected_skills TEXT")
+            if "workflow_id" not in existing_columns:
+                cursor.execute("ALTER TABLE action_items ADD COLUMN workflow_id TEXT")
+            if "input_tokens" not in existing_columns:
+                cursor.execute("ALTER TABLE action_items ADD COLUMN input_tokens INTEGER")
+            if "output_tokens" not in existing_columns:
+                cursor.execute("ALTER TABLE action_items ADD COLUMN output_tokens INTEGER")
+            if "cache_tokens" not in existing_columns:
+                cursor.execute("ALTER TABLE action_items ADD COLUMN cache_tokens INTEGER")
+
             # Create indexes for common queries
             cursor.execute("""
                 CREATE INDEX IF NOT EXISTS idx_action_created_at
@@ -132,13 +172,16 @@ def insert_item(self, item: StoredActionItem) -> None:
         Args:
             item: The StoredActionItem to insert or update.
         """
+        skills_json = json.dumps(item.selected_skills) if item.selected_skills else None
         with sqlite3.connect(self._db_path) as conn:
             cursor = conn.cursor()
             cursor.execute("""
                 INSERT OR REPLACE INTO action_items
                 (id, name, status, item_type, parent_id, created_at,
-                 completed_at, input_data, output_data, error_message)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                 completed_at, input_data, output_data, error_message,
+                 selected_skills, workflow_id,
+                 input_tokens, output_tokens, cache_tokens)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """, (
                 item.id,
                 item.name,
@@ -150,6 +193,11 @@ def insert_item(self, item: StoredActionItem) -> None:
                 item.input_data,
                 item.output_data,
                 item.error_message,
+                skills_json,
+                item.workflow_id,
+                item.input_tokens,
+                item.output_tokens,
+                item.cache_tokens,
             ))
             conn.commit()
 
@@ -218,7 +266,9 @@ def get_items(
 
             query = """
                 SELECT id, name, status, item_type, parent_id, created_at,
-                       completed_at, input_data, output_data, error_message
+                       completed_at, input_data, output_data, error_message,
+                       selected_skills, workflow_id,
+                       input_tokens, output_tokens, cache_tokens
                 FROM action_items
             """
             if not include_running:
@@ -240,6 +290,11 @@ def get_items(
                     input_data=row[7],
                     output_data=row[8],
                     error_message=row[9],
+                    selected_skills=_decode_skills(row[10]),
+                    workflow_id=row[11],
+                    input_tokens=row[12],
+                    output_tokens=row[13],
+                    cache_tokens=row[14],
                 )
                 for row in rows
             ]
@@ -259,7 +314,9 @@ def get_recent_items(self, limit: int = 100) -> List[StoredActionItem]:
             # Get last N items ordered by created_at DESC, then reverse
             cursor.execute("""
                 SELECT id, name, status, item_type, parent_id, created_at,
-                       completed_at, input_data, output_data, error_message
+                       completed_at, input_data, output_data, error_message,
+                       selected_skills, workflow_id,
+                       input_tokens, output_tokens, cache_tokens
                 FROM action_items
                 ORDER BY created_at DESC
                 LIMIT ?
@@ -278,6 +335,11 @@ def get_recent_items(self, limit: int = 100) -> List[StoredActionItem]:
                     input_data=row[7],
                     output_data=row[8],
                     error_message=row[9],
+                    selected_skills=_decode_skills(row[10]),
+                    workflow_id=row[11],
+                    input_tokens=row[12],
+                    output_tokens=row[13],
+                    cache_tokens=row[14],
                 )
                 for row in rows
             ]
@@ -299,7 +361,9 @@ def get_item(self, item_id: str) -> Optional[StoredActionItem]:
             cursor = conn.cursor()
             cursor.execute("""
                 SELECT id, name, status, item_type, parent_id, created_at,
-                       completed_at, input_data, output_data, error_message
+                       completed_at, input_data, output_data, error_message,
+                       selected_skills, workflow_id,
+                       input_tokens, output_tokens, cache_tokens
                 FROM action_items
                 WHERE id = ?
             """, (item_id,))
@@ -317,6 +381,11 @@ def get_item(self, item_id: str) -> Optional[StoredActionItem]:
                     input_data=row[7],
                     output_data=row[8],
                     error_message=row[9],
+                    selected_skills=_decode_skills(row[10]),
+                    workflow_id=row[11],
+                    input_tokens=row[12],
+                    output_tokens=row[13],
+                    cache_tokens=row[14],
                 )
             return None
 
@@ -335,6 +404,52 @@ def clear_items(self) -> int:
             conn.commit()
             return count
 
+    def clear_terminal_tasks(self) -> List[str]:
+        """
+        Delete tasks whose status is completed/error/cancelled, plus all
+        their child actions. Running/waiting tasks are preserved so the
+        user can keep monitoring active work.
+
+        Returns:
+            List of removed item IDs (terminal tasks + their child actions).
+        """
+        terminal_statuses = ("completed", "error", "cancelled")
+        with sqlite3.connect(self._db_path) as conn:
+            cursor = conn.cursor()
+
+            placeholders = ",".join("?" for _ in terminal_statuses)
+            cursor.execute(
+                f"""
+                SELECT id FROM action_items
+                WHERE item_type = 'task' AND status IN ({placeholders})
+                """,
+                terminal_statuses,
+            )
+            terminal_task_ids = [row[0] for row in cursor.fetchall()]
+
+            if not terminal_task_ids:
+                return []
+
+            id_placeholders = ",".join("?" for _ in terminal_task_ids)
+            cursor.execute(
+                f"""
+                SELECT id FROM action_items
+                WHERE id IN ({id_placeholders}) OR parent_id IN ({id_placeholders})
+                """,
+                terminal_task_ids + terminal_task_ids,
+            )
+            removed_ids = [row[0] for row in cursor.fetchall()]
+
+            cursor.execute(
+                f"""
+                DELETE FROM action_items
+                WHERE id IN ({id_placeholders}) OR parent_id IN ({id_placeholders})
+                """,
+                terminal_task_ids + terminal_task_ids,
+            )
+            conn.commit()
+            return removed_ids
+
     def delete_item(self, item_id: str) -> bool:
         """
         Delete an item by ID.
@@ -418,7 +533,9 @@ def get_recent_tasks_with_actions(
             placeholders = ','.join('?' * len(task_ids))
             cursor.execute(f"""
                 SELECT id, name, status, item_type, parent_id, created_at,
-                       completed_at, input_data, output_data, error_message
+                       completed_at, input_data, output_data, error_message,
+                       selected_skills, workflow_id,
+                       input_tokens, output_tokens, cache_tokens
                 FROM action_items
                 WHERE id IN ({placeholders}) OR parent_id IN ({placeholders})
                 ORDER BY created_at ASC
@@ -437,6 +554,11 @@ def get_recent_tasks_with_actions(
                     input_data=row[7],
                     output_data=row[8],
                     error_message=row[9],
+                    selected_skills=_decode_skills(row[10]),
+                    workflow_id=row[11],
+                    input_tokens=row[12],
+                    output_tokens=row[13],
+                    cache_tokens=row[14],
                 )
                 for row in rows
             ]
@@ -473,7 +595,9 @@ def get_tasks_before(
             placeholders = ','.join('?' * len(task_ids))
             cursor.execute(f"""
                 SELECT id, name, status, item_type, parent_id, created_at,
-                       completed_at, input_data, output_data, error_message
+                       completed_at, input_data, output_data, error_message,
+                       selected_skills, workflow_id,
+                       input_tokens, output_tokens, cache_tokens
                 FROM action_items
                 WHERE id IN ({placeholders}) OR parent_id IN ({placeholders})
                 ORDER BY created_at ASC
@@ -492,6 +616,11 @@ def get_tasks_before(
                     input_data=row[7],
                     output_data=row[8],
                     error_message=row[9],
+                    selected_skills=_decode_skills(row[10]),
+                    workflow_id=row[11],
+                    input_tokens=row[12],
+                    output_tokens=row[13],
+                    cache_tokens=row[14],
                 )
                 for row in rows
             ]
diff --git a/app/usage/task_attribution.py b/app/usage/task_attribution.py
new file mode 100644
index 00000000..afdd8599
--- /dev/null
+++ b/app/usage/task_attribution.py
@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""
+app.usage.task_attribution
+
+Shared helper for attributing LLM/VLM usage to the currently-active task.
+
+Called from the `_report_usage` hooks in both `app.llm.interface` and
+`app.vlm_interface`. It bumps cumulative token counters on the active Task
+object and emits a `TASK_TOKEN_UPDATE` UI event so the browser can tick its
+display while the task runs.
+"""
+
+from __future__ import annotations
+
+from agent_core.core.hooks.types import UsageEventData
+
+
+def attribute_usage_to_current_task(event: UsageEventData) -> None:
+    """Bump per-task token counters and emit a UI tick.
+
+    Best-effort: any failure here is swallowed so that token tracking can
+    never break an in-flight LLM/VLM call. If no task is active (e.g.
+    conversation mode), this is a no-op.
+    """
+    try:
+        from app.state.agent_state import STATE
+        from app.logger import logger
+
+        task = STATE.current_task
+        if task is None:
+            logger.debug(
+                f"[TOKEN_ATTR] skipped — no current task "
+                f"(event: in={event.input_tokens} out={event.output_tokens} cached={event.cached_tokens})"
+            )
+            return
+
+        task.input_tokens = (task.input_tokens or 0) + int(event.input_tokens or 0)
+        task.output_tokens = (task.output_tokens or 0) + int(event.output_tokens or 0)
+        task.cache_tokens = (task.cache_tokens or 0) + int(event.cached_tokens or 0)
+
+        logger.info(
+            f"[TOKEN_ATTR] task={task.id} +in={event.input_tokens} "
+            f"+out={event.output_tokens} +cached={event.cached_tokens} "
+            f"-> totals: in={task.input_tokens} out={task.output_tokens} cache={task.cache_tokens}"
+        )
+
+        bus = STATE.event_bus
+        if bus is None:
+            logger.warning(
+                f"[TOKEN_ATTR] task={task.id} counters bumped but no event_bus on STATE "
+                f"(UI will not update until next broadcast)"
+            )
+            return
+
+        from app.ui_layer.events import UIEvent, UIEventType
+        bus.emit(UIEvent(
+            type=UIEventType.TASK_TOKEN_UPDATE,
+            data={
+                "task_id": task.id,
+                "input_tokens": task.input_tokens,
+                "output_tokens": task.output_tokens,
+                "cache_tokens": task.cache_tokens,
+            },
+            task_id=task.id,
+        ))
+    except Exception as e:
+        try:
+            from app.logger import logger
+            logger.warning(f"[TOKEN_ATTR] attribution failed: {e}", exc_info=True)
+        except Exception:
+            pass
diff --git a/app/usage/task_storage.py b/app/usage/task_storage.py
index a5e59f6a..ee78f166 100644
--- a/app/usage/task_storage.py
+++ b/app/usage/task_storage.py
@@ -166,7 +166,7 @@ def get_task_summary(
                 SELECT
                     COUNT(*) as total_tasks,
                     SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed_tasks,
-                    SUM(CASE WHEN status = 'error' THEN 1 ELSE 0 END) as failed_tasks,
+                    SUM(CASE WHEN status IN ('error', 'cancelled') THEN 1 ELSE 0 END) as failed_tasks,
                     SUM(CASE WHEN status = 'cancelled' THEN 1 ELSE 0 END) as cancelled_tasks,
                     SUM(total_cost) as total_cost,
                     AVG(duration_ms) as avg_duration_ms,
diff --git a/app/utils/__init__.py b/app/utils/__init__.py
new file mode 100644
index 00000000..6ba50185
--- /dev/null
+++ b/app/utils/__init__.py
@@ -0,0 +1,11 @@
+"""Tiny host-wide utility helpers.
+
+Add small, generic helpers to the appropriate submodule (``text``, ``dates``,
+``numbers``, …) and re-export here. Submodules stay dependency-light — no
+host-specific imports, no I/O.
+"""
+from .text import csv_list
+
+__all__ = [
+    "csv_list",
+]
diff --git a/app/utils/text.py b/app/utils/text.py
new file mode 100644
index 00000000..ca0c1586
--- /dev/null
+++ b/app/utils/text.py
@@ -0,0 +1,20 @@
+"""Text / string utilities — generic, dependency-light helpers."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+_UNSET = object()
+
+
+def csv_list(text: Optional[str], default: Any = _UNSET) -> Any:
+    """Split a comma-separated string into a stripped, empty-filtered list.
+
+    Examples:
+        csv_list("a, b ,c")          -> ["a", "b", "c"]
+        csv_list("")                 -> []
+        csv_list("", default=None)   -> None
+        csv_list(None, default=[])   -> []
+    """
+    if not text:
+        return [] if default is _UNSET else default
+    return [v.strip() for v in text.split(",") if v.strip()]
diff --git a/app/vlm_interface.py b/app/vlm_interface.py
index 3c71e9e3..5afc8594 100644
--- a/app/vlm_interface.py
+++ b/app/vlm_interface.py
@@ -10,17 +10,17 @@
 
 from agent_core.core.impl.vlm import VLMInterface as _VLMInterface
 from agent_core.core.hooks.types import UsageEventData
-from app.state.agent_state import STATE
+from app.state.agent_state import get_session_props
 
 
 def _get_token_count() -> int:
-    """Get token count from CraftBot's global STATE."""
-    return STATE.get_agent_property("token_count", 0)
+    """Get token count from the active task's StateSession (per-task counter)."""
+    return get_session_props().get_property("token_count", 0)
 
 
 def _set_token_count(count: int) -> None:
-    """Set token count in CraftBot's global STATE."""
-    STATE.set_agent_property("token_count", count)
+    """Set token count on the active task's StateSession (per-task counter)."""
+    get_session_props().set_property("token_count", count)
 
 
 async def _report_usage(event: UsageEventData) -> None:
@@ -57,3 +57,29 @@ def __init__(
             set_token_count=_set_token_count,
             report_usage=_report_usage,  # Report usage to local SQLite storage
         )
+
+    def _report_usage_async(
+        self,
+        service_type: str,
+        provider: str,
+        model: str,
+        input_tokens: int,
+        output_tokens: int,
+        cached_tokens: int = 0,
+    ) -> None:
+        """Override: attribute to active task synchronously, then defer to base.
+        See LLMInterface._report_usage_async for the race-condition rationale.
+        """
+        from app.usage.task_attribution import attribute_usage_to_current_task
+        attribute_usage_to_current_task(UsageEventData(
+            service_type=service_type,
+            provider=provider,
+            model=model,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cached_tokens=cached_tokens,
+        ))
+        super()._report_usage_async(
+            service_type, provider, model,
+            input_tokens, output_tokens, cached_tokens,
+        )
diff --git a/craftbot.py b/craftbot.py
index e5600608..13c87aef 100644
--- a/craftbot.py
+++ b/craftbot.py
@@ -569,26 +569,26 @@ def cmd_stop() -> None:
 
 def cmd_status() -> None:
     """Print whether CraftBot is currently running and whether auto-start is installed."""
-    W = 50
+    W = max(50, len(LOG_FILE) + 12)
     pid = _read_pid()
     print(f"\n{ORANGE}╔{'═' * W}╗{RESET}")
     if pid and _is_running(pid):
         print(
-            f"{ORANGE}║{RESET}  {GREEN}▸ RUNNING{RESET}  {DIM}PID {pid}{RESET}{' ' * (W - 14 - len(str(pid)))}{ORANGE}║{RESET}"
+            f"{ORANGE}║{RESET}  {GREEN}▸ RUNNING{RESET}  {DIM}PID {pid}{RESET}{' ' * (W - 17 - len(str(pid)))}{ORANGE}║{RESET}"
         )
         print(
-            f"{ORANGE}║{RESET}  {DIM}░░ LOG: {LOG_FILE[: W - 8]}{RESET}{' ' * max(0, W - 8 - len(LOG_FILE[: W - 8]))}{ORANGE}║{RESET}"
+            f"{ORANGE}║{RESET}  {DIM}░░ LOG: {LOG_FILE[: W - 8]}{RESET}{' ' * max(0, W - 10 - len(LOG_FILE[: W - 8]))}{ORANGE}║{RESET}"
         )
     else:
         if pid:
             _remove_pid()
         print(
-            f"{ORANGE}║{RESET}  {RED}▸ NOT RUNNING{RESET}{' ' * (W - 14)}{ORANGE}║{RESET}"
+            f"{ORANGE}║{RESET}  {RED}▸ NOT RUNNING{RESET}{' ' * (W - 15)}{ORANGE}║{RESET}"
         )
     print(f"{ORANGE}║{' ' * W}║{RESET}")
     if _is_installed():
         print(
-            f"{ORANGE}║{RESET}  {GREEN}▸ AUTO-START: INSTALLED{RESET}{' ' * (W - 23)}{ORANGE}║{RESET}"
+            f"{ORANGE}║{RESET}  {GREEN}▸ AUTO-START: INSTALLED{RESET}{' ' * (W - 25)}{ORANGE}║{RESET}"
         )
     else:
         print(
diff --git a/craftos_integrations/README.md b/craftos_integrations/README.md
new file mode 100644
index 00000000..9bbf5e6b
--- /dev/null
+++ b/craftos_integrations/README.md
@@ -0,0 +1,698 @@
+# craftos_integrations
+
+A plug-and-play package of 19 external integrations (Discord, Slack, Telegram Bot + User, GitHub, Jira, Notion, LinkedIn, Outlook, Twitter, WhatsApp Web/Business, LINE, Lark, plus per-service Google: Gmail / Calendar / Drive / Docs / YouTube) that any Python host can drop in.
+
+The package owns:
+
+- **Auth flows** — OAuth (with PKCE), invite, interactive (QR), or raw tokens.
+- **Runtime clients** — REST/Gateway/WebSocket/MTProto/Node-bridge, polling listeners.
+- **Credential storage** — JSON files in `<project_root>/.credentials/`.
+- **A registry + autoloader** — drop a file in `integrations/`, restart, done.
+- **A common-ops facade** — `send_message(integration, …)`, `is_connected(…)`, `list_integrations()`, etc.
+- **A standard envelope + REST helpers** — every method returns `{ok, result}` or `{error, details}`; `helpers.request`/`arequest` wrap httpx and emit that shape.
+
+The `integrations/` subfolder is **optional**: if a host ships the framework with no bundled integrations (or a consumer deletes the folder), the package still imports, `initialize_manager()` still boots, and every facade call returns a graceful `{"error": "Unknown integration: ..."}` instead of crashing. Drop in only the integrations you want.
+
+The package owns **no UI opinions**. The host wires its own settings page / slash commands / listener callback.
+
+---
+
+## Quick start
+
+```python
+import asyncio, os
+from pathlib import Path
+from craftos_integrations import configure, initialize_manager, get_handler, send_message
+
+async def on_message(payload: dict) -> None:
+    # payload keys: source, integrationType, contactId, contactName,
+    #               messageBody, channelId, channelName, messageId,
+    #               is_self_message, raw
+    print(f"[{payload['source']}] {payload['contactName']}: {payload['messageBody']}")
+
+async def main():
+    configure(
+        project_root=Path.cwd(),
+        oauth={
+            "GITHUB_CLIENT_ID":    os.getenv("GITHUB_CLIENT_ID"),
+            "GOOGLE_CLIENT_ID":    os.getenv("GOOGLE_CLIENT_ID"),
+            "GOOGLE_CLIENT_SECRET": os.getenv("GOOGLE_CLIENT_SECRET"),
+            # ...etc
+        },
+    )
+
+    # Boot the listener (starts every platform that has stored credentials)
+    manager = await initialize_manager(on_message=on_message)
+
+    # Auth via slash-command-style handler dispatch
+    ok, msg = await get_handler("github").handle("login", ["<personal_access_token>"])
+    print(msg)
+
+    # Send a message via any integration through the facade
+    await send_message("slack", recipient="C12345", text="hi from the agent")
+
+asyncio.run(main())
+```
+
+---
+
+## Architecture
+
+```
+                       ┌──────────────────────────────────────┐
+   configure() ──────▶ │             ConfigStore              │ ◀── (env vars fallback)
+                       │   project_root, oauth, logger, …     │
+                       └──────────────────────────────────────┘
+                                      ▲
+                                      │ read by everything
+       ┌──────────────────────────────┴──────────────────────────────┐
+       │                                                             │
+┌──────────────┐                                            ┌──────────────────┐
+│ Auth side    │                                            │ Runtime side     │
+│              │                                            │                  │
+│ IntegrationHandler  ─◀── @register_handler("name")        │ BasePlatformClient
+│  ├── login                                                │  ├── connect
+│  ├── logout                                               │  ├── send_message
+│  ├── status                                               │  ├── start_listening
+│  ├── invite       (composes OAuthFlow)                    │  ├── stop_listening
+│  ├── connect_token  (default impl on the ABC)             │  └── has_credentials
+│  ├── connect_oauth                                        │       ▲
+│  └── connect_interactive                                  │       │ @register_client
+│                                                           │       │
+│       ▲                                                   │       │
+│       │ both reference the same IntegrationSpec           │       │
+│       │   (composition, not inheritance)                  │       │
+│       ▼                                                   │       │
+│ IntegrationSpec(name, platform_id, cred_class, cred_file) ────────┘
+└──────────────┬─────────────────────────────────┬──────────────────┘
+               │                                 │
+       persists creds to                  manager starts/stops listeners
+               ▼                                 ▼
+       ┌──────────────────┐           ┌──────────────────────┐
+       │ <project_root>/  │           │ ExternalCommsManager │
+       │   .credentials/  │           │  ├── start_platform  │
+       │     <name>.json  │           │  ├── stop_platform   │
+       └──────────────────┘           │  └── on_message ─────┴──▶ host callback
+                                      └──────────────────────┘
+```
+
+Two ABCs per integration — `IntegrationHandler` (auth lifecycle) and `BasePlatformClient` (runtime lifecycle) — bound by composition through a shared `IntegrationSpec`. Both register via decorators; the autoloader walks `integrations/` and triggers them.
+
+---
+
+## Setup
+
+### 1. `configure(...)` — call once at startup
+
+```python
+configure(
+    project_root: Path = Path.cwd(),     # where .credentials/ lives
+    logger: logging.Logger = None,        # falls back to stdlib if None
+    oauth: dict[str, str] = None,         # OAuth client IDs/secrets (see table below)
+    oauth_runner: Callable = None,        # override the bundled localhost server
+    onboarding_hook: Callable = None,     # optional: called on first connect
+    extras: dict = None,                  # arbitrary host-supplied context
+)
+```
+
+Anything not passed falls back to **environment variables** with the same name. So a host that prefers env-only setup can call `configure(project_root=...)` alone.
+
+### 2. `initialize_manager(on_message=...)` — boot the listener
+
+```python
+manager = await initialize_manager(on_message=callback, auto_start=True)
+```
+
+- Walks the `integrations/` folder via `autoload_integrations()`.
+- For each registered platform that supports listening AND has stored credentials, starts a listener.
+- Routes incoming messages through the standardized payload (see below) into your `on_message`.
+
+### 3. Incoming-message payload contract
+
+```python
+{
+    "source":          "Discord",                # human display name (handler.display_name)
+    "integrationType": "discord",                # platform_id
+    "contactId":       "<sender id>",
+    "contactName":     "<sender display name>",
+    "messageBody":     "<text>",
+    "channelId":       "<channel/chat id>",
+    "channelName":     "<channel/chat name>",
+    "messageId":       "<platform message id>",
+    "is_self_message": False,
+    "raw":             { ... },                  # full original platform event
+}
+```
+
+---
+
+## Configuration: OAuth env vars
+
+Every OAuth-capable integration reads its credentials via `ConfigStore.get_oauth(KEY)` — first checking the dict you passed to `configure(oauth=...)`, then falling back to `os.environ[KEY]`.
+
+| Integration       | Auth type   | Required keys                                                            |
+|-------------------|-------------|--------------------------------------------------------------------------|
+| github            | token       | (none — user pastes a personal access token)                             |
+| jira              | token       | (none — user supplies domain + email + API token)                        |
+| twitter           | token       | (none — user supplies 4 OAuth1 keys)                                     |
+| discord           | token       | (none — user pastes a bot token)                                         |
+| whatsapp_business | token       | (none — user supplies access token + phone_number_id)                    |
+| line              | token       | (none — user pastes channel access token + channel secret)               |
+| lark              | token       | (none — user supplies App ID + App Secret from open.larksuite.com)       |
+| telegram_bot      | token       | optional `TELEGRAM_SHARED_BOT_TOKEN`, `TELEGRAM_SHARED_BOT_USERNAME` for `invite` flow |
+| telegram_user     | interactive | `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`                                   |
+| whatsapp_web      | interactive | (none — uses Node bridge + QR scan)                                      |
+| gmail / google_* | oauth+PKCE  | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` (shared across all five Google integrations) |
+| outlook           | oauth+PKCE  | `OUTLOOK_CLIENT_ID`                                                      |
+| linkedin          | oauth       | `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`                           |
+| notion            | both        | `NOTION_SHARED_CLIENT_ID`, `NOTION_SHARED_CLIENT_SECRET` (only for `invite`) |
+| slack             | both        | `SLACK_SHARED_CLIENT_ID`, `SLACK_SHARED_CLIENT_SECRET` (only for `invite`) |
+
+The discord voice helper additionally reads `extras["openai_api_key"]` (or `OPENAI_API_KEY` env) for STT/TTS.
+
+---
+
+## Per-integration runtime config
+
+Some integrations expose **runtime knobs** the user tunes after connecting — Discord's `mention_only`, GitHub's `watch_tag` / `watch_repos`, Twitter's `watch_tag`, WhatsApp Web's `self_messages_only`, etc. The package provides a uniform, schema-driven way to declare these on the handler, persist them to disk, and surface them to UI hosts.
+
+### Shape: declare two attributes on the handler
+
+```python
+@dataclass
+class DiscordConfig:
+    mention_only: bool = False
+    third_party_usernames: List[str] = field(default_factory=list)
+
+
+@register_handler(DISCORD.name)
+class DiscordHandler(IntegrationHandler):
+    spec = DISCORD
+    display_name = "Discord"
+    auth_type = "token"
+    fields = [{"key": "bot_token", "label": "Bot Token", "password": True}]
+
+    config_class = DiscordConfig
+    config_fields = [
+        {"key": "mention_only", "label": "Only when @-mentioned", "type": "checkbox",
+         "help": "Drop messages that don't @-mention the bot."},
+        {"key": "third_party_usernames", "label": "Allowed users", "type": "list",
+         "placeholder": "alice, bob",
+         "help": "Comma-separated Discord usernames or display names."},
+    ]
+```
+
+Both attributes are optional. An integration without `config_class` doesn't expose a configure UI — empty by default.
+
+### Field types
+
+Each entry in `config_fields` is a dict with these keys:
+
+| Key            | Required | Notes                                                                 |
+|----------------|----------|-----------------------------------------------------------------------|
+| `key`          | yes      | Dataclass field name; the value gets written to ``<name>_config.json`` |
+| `label`        | yes      | Human-readable label shown in the UI                                  |
+| `type`         | yes      | One of `text`, `textarea`, `list`, `checkbox`, `select`, `number`     |
+| `placeholder`  | no       | Hint text inside the input                                            |
+| `help`         | no       | Description shown under the field                                     |
+| `options`      | only `select` | Array of `{value, label}` choice objects                         |
+
+The backend coerces incoming UI values to the dataclass field types — `checkbox` to bool, `list` from `"a, b, c"` strings into `["a","b","c"]`, `number` parses to int/float, etc.
+
+### Storage
+
+Config is persisted at `<project_root>/.credentials/<name>_config.json` — same directory as credentials, with a `_config.json` suffix:
+
+```
+.credentials/
+├── discord.json              ← credential (token, etc.)
+├── discord_config.json       ← runtime config (mention_only, allowlists)
+├── github.json
+├── github_config.json
+└── ...
+```
+
+Unknown keys in older config files are silently dropped on load, and missing fields fall back to dataclass defaults — so adding/removing a field is one line and doesn't break existing installs.
+
+### Reading config from your client
+
+Use `craftos_integrations.load_config` inside `start_listening` or message handlers:
+
+```python
+from craftos_integrations import load_config
+
+async def _handle_message(self, data):
+    cfg = load_config("discord_config.json", DiscordConfig) or DiscordConfig()
+    if cfg.mention_only and not bot_was_mentioned:
+        return
+    ...
+```
+
+Reading fresh on each message keeps config changes effective without a restart.
+
+### Host-side facade
+
+Three async-friendly helpers on `craftos_integrations` parallel the credential ones:
+
+```python
+from craftos_integrations import (
+    get_config,         # current values as a plain dict (defaults if no file yet)
+    update_config,      # write new values; coerces per the schema
+    get_config_schema,  # the config_fields list, for rendering a settings form
+)
+
+get_config("discord")
+# → {"mention_only": False, "third_party_usernames": []}
+
+ok, msg = update_config("discord", {"mention_only": True, "third_party_usernames": "alice, bob"})
+# Backend coerces the string into ["alice", "bob"] and persists
+
+get_config_schema("discord")
+# → [{"key": "mention_only", "label": "Only when @-mentioned", "type": "checkbox", ...}, ...]
+```
+
+### Inline connect help (the `?` popover)
+
+Independent of `config_class`, handlers can declare a `connect_help: List[str]` for "where do I find these credentials" guidance shown in the connect modal:
+
+```python
+@register_handler(LINE.name)
+class LineHandler(IntegrationHandler):
+    ...
+    connect_help = [
+        "Open LINE Developers Console: developers.line.biz/console",
+        "Sign in with your LINE account",
+        "Create a Provider, then create a Messaging API channel inside it",
+        "Channel Secret → Basic settings tab → 'Channel secret' field",
+        "Channel Access Token → Messaging API tab → 'Issue' button (long-lived)",
+    ]
+```
+
+Steps surface to UI hosts via `get_metadata(integration)["connect_help"]` and are rendered as a numbered list when the user clicks the `?` icon in the connect dialog.
+
+---
+
+## Auth: three ways to connect
+
+Every handler exposes three **dispatchers** on the ABC. Hosts call the one that matches the integration's `auth_type`:
+
+| Dispatcher                                  | Used by `auth_type`              |
+|---------------------------------------------|----------------------------------|
+| `connect_token(integration, creds_dict)`    | `token`, `both`, `token_with_interactive` |
+| `connect_oauth(integration)`                | `oauth`, `both`                  |
+| `connect_interactive(integration)`          | `interactive`, `token_with_interactive` |
+
+```python
+from craftos_integrations import connect_token, connect_oauth, connect_interactive, disconnect
+
+# Token — host collects field values matching handler.fields
+ok, msg = await connect_token("github", {"access_token": "ghp_..."})
+
+# OAuth — opens the browser, captures the redirect on localhost:8765
+ok, msg = await connect_oauth("google")
+
+# Interactive — e.g. WhatsApp QR scan, Telegram phone-code
+ok, msg = await connect_interactive("whatsapp_web")
+
+# Disconnect
+ok, msg = await disconnect("github")
+```
+
+By default each dispatcher **also starts the listener** for the platform on success. Pass `start_listener=False` to skip.
+
+For UI-driven flows where you want metadata (display name, fields, auth type) to render a settings form:
+
+```python
+from craftos_integrations import list_metadata, get_metadata, integration_registry
+
+list_metadata()                # all integrations as a list
+get_metadata("slack")          # single integration
+integration_registry()         # snapshot dict {id: metadata}
+```
+
+---
+
+## Adding a new integration
+
+One file. Drop it in `craftos_integrations/integrations/<name>.py`. The autoloader picks it up at startup.
+
+### Minimal token-only example (e.g. Asana)
+
+```python
+# craftos_integrations/integrations/asana.py
+from dataclasses import dataclass, field
+from typing import List, Tuple
+
+from .. import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    has_credential, load_credential, save_credential, remove_credential,
+    register_client, register_handler,
+)
+from ..helpers import Result, request as http_request
+from ..logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class AsanaCredential:
+    access_token: str = ""
+    workspace_id: str = ""
+
+
+ASANA = IntegrationSpec(
+    name="asana",
+    platform_id="asana",
+    cred_class=AsanaCredential,
+    cred_file="asana.json",
+)
+
+
+@dataclass
+class AsanaConfig:
+    project_filter: List[str] = field(default_factory=list)
+
+
+@register_handler(ASANA.name)
+class AsanaHandler(IntegrationHandler):
+    spec = ASANA
+    display_name = "Asana"
+    description = "Tasks and projects"
+    auth_type = "token"
+    icon = "asana"                                              # Lucide icon name or frontend brand-SVG key
+    fields = [
+        {"key": "access_token", "label": "Personal Access Token",
+         "placeholder": "1/12345...", "password": True},
+    ]
+
+    # Inline help shown in the connect modal's ``?`` popover
+    connect_help = [
+        "Open https://app.asana.com/0/my-apps",
+        "Click 'Create new token' → name it, copy the token",
+    ]
+
+    # Optional runtime config — schema-driven UI for post-connect knobs.
+    # Omit both attrs if your integration has no runtime settings.
+    config_class = AsanaConfig
+    config_fields = [
+        {"key": "project_filter", "label": "Watched projects", "type": "list",
+         "placeholder": "GID1, GID2",
+         "help": "Comma-separated Asana project GIDs. Empty = watch all."},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        # `args` is the credential values in field-declaration order
+        # (the default connect_token() on the ABC builds it from a dict)
+        token = args[0] if args else ""
+        if not token:
+            return False, "Personal access token is required."
+
+        result = http_request(
+            "GET", "https://app.asana.com/api/1.0/users/me",
+            headers={"Authorization": f"Bearer {token}"},
+            expected=(200,),
+        )
+        if "error" in result:
+            return False, f"Asana auth failed: {result['error']}"
+        me = (result["result"] or {}).get("data", {})
+
+        save_credential(self.spec.cred_file, AsanaCredential(access_token=token))
+        return True, f"Asana connected as {me.get('name', 'unknown')}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Asana credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Asana credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Asana: Not connected"
+        return True, "Asana: Connected"
+
+
+@register_client
+class AsanaClient(BasePlatformClient):
+    spec = ASANA
+    PLATFORM_ID = ASANA.platform_id
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> AsanaCredential:
+        cred = load_credential(self.spec.cred_file, AsanaCredential)
+        if cred is None:
+            raise RuntimeError("No Asana credentials. Use /asana login first.")
+        return cred
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        # Asana doesn't really do "send_message" — repurpose for adding a comment to a task
+        cred = self._load()
+        return http_request(
+            "POST", f"https://app.asana.com/api/1.0/tasks/{recipient}/stories",
+            headers={"Authorization": f"Bearer {cred.access_token}"},
+            json={"data": {"text": text}},
+            transform=lambda d: d.get("data"),
+        )
+```
+
+That's it. No edits to `manager.py`, no central registry, no `__init__.py` changes. Restart the host, `get_handler("asana")` resolves, settings UI renders the form from `fields`.
+
+#### About `helpers.request` / `Result`
+
+The package ships a thin `httpx` wrapper at `craftos_integrations.helpers`. It owns the standard envelope so every integration returns the same shape:
+
+```python
+# Success
+{"ok": True, "result": <transformed body>}
+
+# Failure (HTTP non-2xx, network error, exception)
+{"error": "<message>", "details": "<response text or omitted>"}
+```
+
+Both shapes are codified as TypedDicts (`Ok`, `Err`, `Result`) — you just import `Result` and use it as the return annotation. `request` is the sync wrapper; `arequest` is the async one. Pass `expected=(...)` to override the success status set (default `(200, 201)`), `transform=` to reshape the parsed body, and `timeout=` to override the 15s default.
+
+Three integrations (Slack, Telegram Bot, Notion) layer file-private wrappers on top of `request`/`arequest` because their wire envelope differs (Slack/Telegram bake `ok: bool` into the body, Notion returns errors as parsed JSON bodies). That's the only reason to deviate from the helper.
+
+### OAuth example (using `OAuthFlow`)
+
+For OAuth integrations, **compose** an `OAuthFlow` instance on the handler instead of writing the auth dance:
+
+```python
+from .. import OAuthFlow
+
+@register_handler(ASANA.name)
+class AsanaHandler(IntegrationHandler):
+    spec = ASANA
+    display_name = "Asana"
+    description = "Tasks and projects"
+    auth_type = "oauth"
+    fields: List = []
+
+    oauth = OAuthFlow(
+        client_id_key="ASANA_CLIENT_ID",
+        client_secret_key="ASANA_CLIENT_SECRET",
+        auth_url="https://app.asana.com/-/oauth_authorize",
+        token_url="https://app.asana.com/-/oauth_token",
+        userinfo_url="https://app.asana.com/api/1.0/users/me",
+        scopes="default",
+    )
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        result = await self.oauth.run()
+        if "error" in result and not result.get("access_token"):
+            return False, f"Asana OAuth failed: {result['error']}"
+        info = result.get("userinfo", {}).get("data", {})
+        save_credential(self.spec.cred_file, AsanaCredential(
+            access_token=result["access_token"],
+        ))
+        return True, f"Asana connected as {info.get('name')}"
+```
+
+`OAuthFlow.run()` opens the browser, captures the callback on localhost:8765, exchanges the code for tokens, and (optionally) fetches the userinfo. Supports PKCE, HTTPS callback, custom auth params.
+
+### Auth types reference
+
+| `auth_type`              | Meaning                                                                |
+|--------------------------|------------------------------------------------------------------------|
+| `token`                  | Raw token / API key paste                                              |
+| `oauth`                  | Browser OAuth (uses `OAuthFlow` and the bundled localhost server)     |
+| `both`                   | Has both an `invite` (OAuth) **and** a `login` (token) path           |
+| `interactive`            | QR code scan or phone code (e.g. WhatsApp Web, Telegram user)         |
+| `token_with_interactive` | Has both                                                              |
+
+### Folder layout per integration
+
+Each integration lives in its own folder under `integrations/`. The handler + client go in `__init__.py`, docs in `INTEGRATION.md`, and any supporting modules sit alongside with an **underscore prefix** so the autoloader skips them. Helpers shared by multiple integrations (`_google_common.py`, `_lark_common.py`) stay at the `integrations/` root.
+
+```
+craftos_integrations/integrations/
+├── _google_common.py          ← shared by gmail / google_* (autoloader skips)
+├── _lark_common.py            ← shared by lark / lark_* (autoloader skips)
+├── discord/
+│   ├── __init__.py            ← handler + client
+│   ├── INTEGRATION.md
+│   └── _discord_voice.py      ← skipped by autoloader
+├── telegram_user/
+│   ├── __init__.py
+│   ├── INTEGRATION.md
+│   └── _telegram_mtproto.py   ← skipped by autoloader
+├── whatsapp_web/
+│   ├── __init__.py
+│   ├── INTEGRATION.md
+│   ├── _bridge_client.py      ← skipped by autoloader
+│   ├── bridge.js              ← Node sidecar
+│   └── package.json
+├── github/
+│   └── __init__.py
+└── ... (one folder per integration)
+```
+
+---
+
+## Public API reference
+
+### Setup
+- `configure(*, project_root, logger, oauth, oauth_runner, onboarding_hook, extras)` — call once at startup
+- `initialize_manager(*, on_message, auto_start=True) -> ExternalCommsManager`
+- `get_external_comms_manager() -> ExternalCommsManager | None`
+
+### Registry
+- `autoload_integrations(force=False)` — walks `integrations/`, imports every file (decorators fire)
+- `register_client`, `register_handler(name)` — decorators
+- `get_client(platform_id)` / `get_handler(name)` — singleton per registered class
+- `get_all_clients()` / `get_all_handlers()`
+- `get_registered_platforms()` / `get_registered_handler_names()`
+
+### Common ops (the facade)
+- `send_message(integration, recipient, text, **kw) -> dict` (async)
+- `is_connected(integration) -> bool`
+- `list_connected() -> list[str]` — names of platforms that have stored credentials
+- `list_all() -> list[str]` — every registered integration
+- `disconnect(integration, account_id=None) -> (bool, str)` (async)
+- `status(integration) -> (bool, str)` (async)
+
+### Connect dispatchers (auto-start listener on success)
+- `connect_token(integration, creds: dict, *, start_listener=True) -> (bool, str)`
+- `connect_oauth(integration, *, start_listener=True) -> (bool, str)`
+- `connect_interactive(integration, *, start_listener=True) -> (bool, str)`
+
+### Metadata
+- `get_metadata(integration) -> dict | None`
+  - Shape: `{id, name, description, auth_type, fields, icon, has_config, config_fields, connect_help}`
+  - `has_config: bool` — True when the handler declared a `config_class`
+  - `config_fields: list[dict] | None` — the runtime-config render schema (None when no config)
+  - `connect_help: list[str] | None` — inline setup steps for the `?` popover
+- `list_metadata() -> list[dict]`
+- `integration_registry() -> dict[str, dict]`
+- `get_integration_info(integration) -> dict` (async; metadata + live `connected` + `accounts`)
+- `list_integrations() -> list[dict]` (async)
+- `parse_status_accounts(msg) -> list[dict]`
+
+### Per-integration runtime config (post-connect knobs)
+- `get_config(integration) -> dict | None` — current values; defaults when no file yet; `None` if no `config_class` declared
+- `update_config(integration, values: dict) -> (bool, str)` — coerces values per the schema, persists
+- `get_config_schema(integration) -> list[dict] | None` — the `config_fields` list, for rendering a form
+
+### Sync flavors (for TUI / synchronous callers)
+- `list_integrations_sync()`
+- `get_integration_info_sync(integration)`
+- `get_integration_fields(integration)`
+- `get_integration_auth_type(integration)`
+- `get_integration_accounts(integration)`
+
+### Credentials
+- `save_credential(filename, dataclass_instance)`
+- `load_credential(filename, cls) -> instance | None`
+- `has_credential(filename) -> bool`
+- `remove_credential(filename) -> bool`
+
+### Config (same on-disk layout, `_config.json` suffix)
+- `save_config(filename, dataclass_instance)` — filename should end in `_config.json`
+- `load_config(filename, cls) -> instance | None`
+- `has_config(filename) -> bool`
+- `remove_config(filename) -> bool`
+
+### OAuth helper
+- `OAuthFlow(*, client_id_key, client_secret_key, auth_url, token_url, userinfo_url=None, scopes, use_pkce=False, use_https=False, ...)`
+- `REDIRECT_URI` / `REDIRECT_URI_HTTPS` — the bundled callback URLs
+
+### HTTP helpers (package-internal, used by every REST integration)
+- `from craftos_integrations.helpers import request, arequest, Result, Ok, Err`
+- `request(method, url, *, headers, json, params, data, files, expected=(200, 201), transform=None, timeout=15.0) -> Result` — sync httpx wrapper
+- `arequest(...) -> Result` — async variant
+- `Result` — `Ok | Err` TypedDict union for return annotations
+
+### Discovery
+- `PLATFORM_TO_ACTION_SET` / `ACTION_SET_SEND_ACTIONS` — for an action router
+- `get_connected_messaging_platforms() -> list[str]`
+- `get_messaging_actions_for_platforms(platforms) -> list[str]`
+
+### WhatsApp Web QR (non-blocking UIs)
+- `from craftos_integrations.integrations.whatsapp_web import (start_qr_session, check_qr_session_status, cancel_qr_session)`
+
+---
+
+## Listener wiring details
+
+When a successful connect happens, the `connect_token/oauth/interactive` dispatchers automatically call `manager.start_platform(handler.spec.platform_id)`. The manager:
+
+1. Resolves the registered `BasePlatformClient` for that `platform_id`.
+2. If `client.supports_listening` is True and `client.has_credentials()` is True, calls `client.start_listening(callback)`.
+3. The client polls / connects via WebSocket / spawns its bridge, normalizes incoming events to a `PlatformMessage`, and the manager forwards the normalized dict to `on_message`.
+
+Stop ordering is symmetric: `manager.stop_platform(...)` → `client.stop_listening()` → cancels the poll loop / closes the gateway.
+
+---
+
+## Where credentials live
+
+```
+<project_root>/.credentials/
+├── github.json               github_config.json            ← optional runtime-config sibling
+├── gmail.json                gmail_config.json
+├── google_calendar.json      …
+├── google_docs.json
+├── google_drive.json
+├── google_youtube.json
+├── slack.json
+├── discord.json              discord_config.json
+├── jira.json                 jira_config.json
+├── linkedin.json
+├── notion.json
+├── outlook.json
+├── twitter.json              twitter_config.json
+├── line.json                 line_config.json
+├── lark.json
+├── telegram_bot.json         telegram_bot_config.json
+├── telegram_user.json        telegram_user_config.json
+├── whatsapp_business.json
+├── whatsapp_web.json         whatsapp_web_config.json
+└── whatsapp_wwebjs_auth/     ← WhatsApp Web's wwebjs session (browser profile dir)
+```
+
+Two file types live side-by-side: `<name>.json` holds the credential (token, OAuth refresh token, session) and `<name>_config.json` holds the optional post-connect runtime config (watch tags, allowlists, filters). Both are written with mode `0600`; the directory is `0700`. Format is the dataclass serialized via `asdict()`.
+
+---
+
+## Glossary
+
+| Term                     | Meaning                                                                |
+|--------------------------|------------------------------------------------------------------------|
+| `IntegrationSpec`        | Frozen dataclass shared between handler and client (composition glue) |
+| `IntegrationHandler`     | Auth lifecycle ABC: login / logout / status / invite / connect_*      |
+| `BasePlatformClient`     | Runtime lifecycle ABC: connect / send_message / start_listening / stop_listening |
+| `PlatformMessage`        | Normalized incoming-message dataclass (every listener emits these)    |
+| `ConfigStore`            | Singleton holding the host's setup (populated by `configure(...)`)    |
+| `ExternalCommsManager`   | Owns active listeners + on_message routing                            |
+| `OAuthFlow`              | Composition helper for OAuth handlers; runs the localhost callback server + token exchange |
+| `autoload_integrations`  | Walks `integrations/` and imports every module (triggers decorators)  |
+| `display_name` / `name` / `platform_id` | UI label / handler-registry key (slash command) / client-registry key |
+| `Result` / `Ok` / `Err`  | TypedDicts for the standard `{ok, result} / {error, details}` envelope |
+| `request` / `arequest`   | Sync/async httpx wrappers in `helpers/` that emit the standard envelope |
diff --git a/craftos_integrations/__init__.py b/craftos_integrations/__init__.py
new file mode 100644
index 00000000..382dbedc
--- /dev/null
+++ b/craftos_integrations/__init__.py
@@ -0,0 +1,160 @@
+"""craftos_integrations — plug-and-play external integrations.
+
+Quick start:
+
+    import asyncio
+    from craftos_integrations import configure, initialize_manager, get_handler
+
+    async def on_message(payload):
+        print(f"[{payload['source']}] {payload['contactName']}: {payload['messageBody']}")
+
+    async def main():
+        configure(
+            project_root=".",
+            oauth={"GITHUB_CLIENT_ID": "...", ...},
+        )
+        manager = await initialize_manager(on_message=on_message)
+        # auth flows go through handlers:
+        ok, msg = await get_handler("github").handle("login", ["<pat>"])
+        print(msg)
+
+    asyncio.run(main())
+
+Adding a new integration: create a folder under
+craftos_integrations/integrations/ with an ``__init__.py`` (handler +
+client) and an optional ``INTEGRATION.md``. It is auto-loaded at startup.
+See integrations/github/ for the canonical shape.
+"""
+from __future__ import annotations
+
+# Apply runtime compatibility shim before any submodule that uses asyncio.timeout
+# imports it (websockets, aiohttp, etc.). See _runtime_compat.py for details.
+from ._runtime_compat import apply_asyncio_timeout_shim as _apply_timeout_shim
+
+_apply_timeout_shim()
+
+from .base import (
+    BasePlatformClient,
+    IntegrationHandler,
+    MessageCallback,
+    PlatformMessage,
+)
+from .config import ConfigStore, configure
+from .credentials_store import (
+    has_config,
+    has_credential,
+    load_config,
+    load_credential,
+    remove_config,
+    remove_credential,
+    save_config,
+    save_credential,
+)
+from .manager import (
+    ExternalCommsManager,
+    get_external_comms_manager,
+    initialize_manager,
+)
+from .oauth_flow import OAuthFlow, REDIRECT_URI, REDIRECT_URI_HTTPS
+from .registry import (
+    autoload_integrations,
+    get_all_clients,
+    get_all_handlers,
+    get_client,
+    get_handler,
+    get_registered_handler_names,
+    get_registered_platforms,
+    register_client,
+    register_handler,
+)
+from .service import (
+    connect_interactive,
+    connect_oauth,
+    connect_token,
+    disconnect,
+    get_config,
+    get_config_schema,
+    get_integration_accounts,
+    get_integration_auth_type,
+    get_integration_fields,
+    get_integration_info,
+    get_integration_info_sync,
+    get_metadata,
+    integration_registry,
+    is_connected,
+    list_all,
+    list_connected,
+    list_integrations,
+    list_integrations_sync,
+    list_metadata,
+    parse_status_accounts,
+    send_message,
+    status,
+    update_config,
+)
+from .spec import IntegrationSpec
+
+__all__ = [
+    # Setup
+    "configure",
+    "ConfigStore",
+    "initialize_manager",
+    "get_external_comms_manager",
+    "ExternalCommsManager",
+    # Base classes / types
+    "BasePlatformClient",
+    "IntegrationHandler",
+    "PlatformMessage",
+    "MessageCallback",
+    "IntegrationSpec",
+    # Registry
+    "register_client",
+    "register_handler",
+    "get_client",
+    "get_handler",
+    "get_all_clients",
+    "get_all_handlers",
+    "get_registered_platforms",
+    "get_registered_handler_names",
+    "autoload_integrations",
+    # Credentials
+    "save_credential",
+    "load_credential",
+    "has_credential",
+    "remove_credential",
+    # Per-integration runtime config
+    "save_config",
+    "load_config",
+    "has_config",
+    "remove_config",
+    "get_config",
+    "update_config",
+    "get_config_schema",
+    # OAuth helper
+    "OAuthFlow",
+    "REDIRECT_URI",
+    "REDIRECT_URI_HTTPS",
+    # Common-ops facade
+    "send_message",
+    "is_connected",
+    "list_connected",
+    "list_all",
+    "disconnect",
+    "status",
+    # Metadata + connect dispatchers
+    "get_metadata",
+    "list_metadata",
+    "get_integration_info",
+    "list_integrations",
+    "parse_status_accounts",
+    "connect_token",
+    "connect_oauth",
+    "connect_interactive",
+    # Sync wrappers + helpers (for TUI / synchronous callers)
+    "list_integrations_sync",
+    "get_integration_info_sync",
+    "get_integration_accounts",
+    "get_integration_auth_type",
+    "get_integration_fields",
+    "integration_registry",
+]
diff --git a/craftos_integrations/_runtime_compat.py b/craftos_integrations/_runtime_compat.py
new file mode 100644
index 00000000..022d7f4a
--- /dev/null
+++ b/craftos_integrations/_runtime_compat.py
@@ -0,0 +1,103 @@
+"""Runtime compatibility shims for environments where asyncio task context
+gets lost or never registered.
+
+Specifically: on some Python 3.14 conda-forge builds inside this host,
+``asyncio.current_task()`` returns ``None`` even inside a coroutine started
+via ``asyncio.create_task()``. That breaks any third-party library that uses
+``asyncio.timeout(...)`` (websockets, aiohttp, etc.) because
+``Timeout.__aenter__`` raises ``RuntimeError("Timeout should be used inside
+a task")`` when ``current_task()`` is ``None``.
+
+This shim relaxes that check: if ``current_task()`` is ``None``, the
+timeout context simply runs without arming a deadline. When a task IS
+detected, the original behavior is preserved.
+
+The shim is idempotent and applied once at package import.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+
+_APPLIED = False
+
+
+def apply_asyncio_timeout_shim() -> None:
+    """Patch ``asyncio.timeouts.Timeout.__aenter__`` to tolerate missing tasks.
+
+    Only applied on Python 3.11+ (where ``asyncio.timeouts`` exists). No-op on
+    older versions, since they use ``async_timeout`` and have a separate fix path.
+    """
+    global _APPLIED
+    if _APPLIED:
+        return
+    if sys.version_info < (3, 11):
+        _APPLIED = True
+        return
+
+    try:
+        from asyncio import timeouts as _t
+    except ImportError:
+        _APPLIED = True
+        return
+
+    Timeout = _t.Timeout
+    original_aenter = Timeout.__aenter__
+
+    async def patched_aenter(self):
+        # Try the original first; if it would raise solely because there's no
+        # task, fall through and let the body run unguarded.
+        try:
+            return await original_aenter(self)
+        except RuntimeError as e:
+            if "Timeout should be used inside a task" in str(e):
+                # Mark as entered so __aexit__ doesn't object, but don't arm
+                # a deadline. Since most callers in this codebase pass
+                # ``timeout=None`` anyway, no real timeout is being lost.
+                if hasattr(_t, "_State"):
+                    self._state = _t._State.ENTERED
+                self._task = None
+                return self
+            raise
+
+    Timeout.__aenter__ = patched_aenter
+
+    # Also patch __aexit__ to not crash when self._task is None.
+    original_aexit = Timeout.__aexit__
+
+    async def patched_aexit(self, exc_type, exc_val, exc_tb):
+        if self._task is None:
+            # We never armed; just transition state cleanly.
+            if hasattr(_t, "_State"):
+                self._state = _t._State.EXITED
+            return None
+        return await original_aexit(self, exc_type, exc_val, exc_tb)
+
+    Timeout.__aexit__ = patched_aexit
+
+    # Also patch sniffio (used by anyio/httpx) which checks
+    # ``asyncio.current_task()`` for the same reason and raises
+    # ``AsyncLibraryNotFoundError("unknown async library, or not in async
+    # context")`` when it's None. Force it to assume asyncio whenever we
+    # can detect a running loop — the alternatives (trio/curio) aren't in
+    # play for this codebase.
+    try:
+        import sniffio  # type: ignore[import-untyped]
+        original_sniff = sniffio.current_async_library
+
+        def patched_sniff() -> str:
+            try:
+                return original_sniff()
+            except sniffio.AsyncLibraryNotFoundError:
+                try:
+                    asyncio.get_running_loop()
+                    return "asyncio"
+                except RuntimeError:
+                    raise
+
+        sniffio.current_async_library = patched_sniff
+    except ImportError:
+        pass
+
+    _APPLIED = True
diff --git a/craftos_integrations/base.py b/craftos_integrations/base.py
new file mode 100644
index 00000000..69041cfc
--- /dev/null
+++ b/craftos_integrations/base.py
@@ -0,0 +1,183 @@
+"""Base classes for integrations.
+
+Two abstract lifecycles, intentionally separate:
+
+  * IntegrationHandler — login / logout / status / invite (auth flows)
+  * BasePlatformClient — connect / send_message / start_listening (runtime)
+
+Each integration declares one of each, both holding the same IntegrationSpec
+(composition). The two classes do not share a base — they are collaborators.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Runtime side: PlatformMessage + BasePlatformClient
+# ════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class PlatformMessage:
+    platform: str
+    sender_id: str
+    sender_name: str = ""
+    text: str = ""
+    channel_id: str = ""
+    channel_name: str = ""
+    message_id: str = ""
+    timestamp: Optional[datetime] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+
+MessageCallback = Callable[[PlatformMessage], Awaitable[None]]
+
+
+class BasePlatformClient(ABC):
+    PLATFORM_ID: str = ""
+
+    def __init__(self) -> None:
+        self._connected = False
+        self._listening = False
+        self._message_callback: Optional[MessageCallback] = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self._connected
+
+    @property
+    def is_listening(self) -> bool:
+        return self._listening
+
+    @abstractmethod
+    def has_credentials(self) -> bool: ...
+
+    @abstractmethod
+    async def connect(self) -> None: ...
+
+    async def disconnect(self) -> None:
+        if self._listening:
+            await self.stop_listening()
+        self._connected = False
+
+    @abstractmethod
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]: ...
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    async def start_listening(self, callback: MessageCallback) -> None:
+        raise NotImplementedError(f"{self.PLATFORM_ID} does not support listening")
+
+    async def stop_listening(self) -> None:
+        self._listening = False
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Auth side: IntegrationHandler
+# ════════════════════════════════════════════════════════════════════════
+
+class IntegrationHandler(ABC):
+    # ----- UI / metadata (override on each handler) -----
+    display_name: str = ""
+    description: str = ""
+    # auth_type: "token" | "oauth" | "both" | "interactive" | "token_with_interactive"
+    auth_type: str = "token"
+    fields: List[Dict[str, Any]] = []
+    # Lucide icon name (PascalCase) shown on the integration card when the
+    # frontend doesn't have a hand-crafted SVG override. See lucide.dev for
+    # the full set — examples: "Github", "Linkedin", "Send", "MessageCircle",
+    # "Mail", "FileText". Empty string falls back to a generic icon.
+    icon: str = ""
+    # Optional inline guidance shown when the user clicks the "?" button
+    # in the connect modal. Each entry is one step / one place to look —
+    # the frontend renders them as a numbered list inside a popover.
+    # Keep entries short and action-oriented ("Open X console", "Copy
+    # the Y token from the Z tab") — the goal is "where do I find this",
+    # not a full tutorial. ``None`` hides the "?" button.
+    connect_help: Optional[List[str]] = None
+
+    # ----- Optional runtime config (post-connect knobs) -----
+    # ``config_class`` is a plain ``@dataclass`` whose fields hold the
+    # per-integration settings users tune from the Configure UI (e.g.
+    # ``watch_tag``, ``watch_repos``, ``channel_filter``). ``config_fields``
+    # is the matching render schema the frontend uses to draw the form.
+    # Both default to "no config" — the Configure section is hidden for
+    # integrations that don't declare them. See ``service.get_config`` /
+    # ``service.update_config`` for how they get loaded and saved.
+    #
+    # Schema entry shape:
+    #   {"key": "watch_tag", "label": "Watch tag",
+    #    "type": "text" | "textarea" | "list" | "checkbox" | "select" | "number",
+    #    "placeholder": "@craftbot",      # optional
+    #    "help": "Trigger keyword.",      # optional
+    #    "options": [...]}                # required when type=="select"
+    config_class: Optional[type] = None
+    config_fields: List[Dict[str, Any]] = []
+
+    @abstractmethod
+    async def login(self, args: List[str]) -> Tuple[bool, str]: ...
+
+    @abstractmethod
+    async def logout(self, args: List[str]) -> Tuple[bool, str]: ...
+
+    @abstractmethod
+    async def status(self) -> Tuple[bool, str]: ...
+
+    async def invite(self, args: List[str]) -> Tuple[bool, str]:
+        return False, "Invite not available for this integration. Use 'login' instead."
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["login", "logout", "status"]
+
+    async def handle(self, sub: str, args: List[str]) -> Tuple[bool, str]:
+        if sub == "invite":
+            return await self.invite(args)
+        if sub == "login":
+            return await self.login(args)
+        if sub == "logout":
+            return await self.logout(args)
+        if sub == "status":
+            return await self.status()
+        return False, f"Unknown subcommand: {sub}. Use: {', '.join(self.subcommands)}"
+
+    # ----- Default connect dispatchers (overridable per handler) -----
+
+    async def connect_token(self, creds: Dict[str, str]) -> Tuple[bool, str]:
+        """Map a {field_key: value} dict to login() args, in field-declaration order."""
+        if not self.fields:
+            return False, f"Token-based login not supported for {self.display_name or 'this integration'}"
+        args: List[str] = []
+        for field in self.fields:
+            key = field["key"]
+            value = creds.get(key, "")
+            if not value and not field.get("optional"):
+                label = field.get("label", key)
+                return False, f"{label} is required"
+            args.append(value)
+        # Drop trailing optional empties so handler.login can use len(args) checks
+        while args and not args[-1]:
+            field_def = self.fields[len(args) - 1]
+            if field_def.get("optional"):
+                args.pop()
+            else:
+                break
+        return await self.login(args)
+
+    async def connect_oauth(self, args: Optional[List[str]] = None) -> Tuple[bool, str]:
+        """OAuth dispatcher: prefers invite() for 'both' auth, else login()."""
+        a = args or []
+        if self.auth_type == "both" and hasattr(self, "invite"):
+            return await self.invite(a)
+        return await self.login(a)
+
+    async def connect_interactive(self, args: Optional[List[str]] = None) -> Tuple[bool, str]:
+        """Interactive (e.g. QR scan) dispatcher: prefers 'login-qr' subcommand if exposed."""
+        a = args or []
+        sub = "login-qr" if "login-qr" in self.subcommands else "login"
+        return await self.handle(sub, a)
diff --git a/craftos_integrations/config.py b/craftos_integrations/config.py
new file mode 100644
index 00000000..3136155f
--- /dev/null
+++ b/craftos_integrations/config.py
@@ -0,0 +1,64 @@
+"""Host-injected configuration for the integrations package.
+
+The host calls configure(...) once at startup. Every module reads from
+ConfigStore — no module imports from the host application.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple
+
+OAuthRunner = Callable[..., Awaitable[Tuple[Optional[str], Optional[str]]]]
+MessageCallback = Callable[[Dict[str, Any]], Awaitable[None]]
+OnboardingHook = Callable[[str, Dict[str, Any]], Awaitable[None]]
+
+
+class ConfigStore:
+    project_root: Path = Path.cwd()
+    logger: Optional[logging.Logger] = None
+    on_message: Optional[MessageCallback] = None
+    oauth_runner: Optional[OAuthRunner] = None
+    onboarding_hook: Optional[OnboardingHook] = None
+    extras: Dict[str, Any] = {}
+    _oauth: Dict[str, str] = {}
+
+    @classmethod
+    def get_oauth(cls, key: str, default: str = "") -> str:
+        if key in cls._oauth and cls._oauth[key]:
+            return cls._oauth[key]
+        return os.environ.get(key, default)
+
+    @classmethod
+    def require_oauth(cls, key: str) -> str:
+        value = cls.get_oauth(key)
+        if not value:
+            raise RuntimeError(
+                f"Integrations: required OAuth setting '{key}' is not configured. "
+                f"Pass it to configure(oauth={{...}}) or set the {key} env var."
+            )
+        return value
+
+
+def configure(
+    *,
+    project_root: Optional[Path] = None,
+    logger: Optional[logging.Logger] = None,
+    oauth: Optional[Dict[str, str]] = None,
+    oauth_runner: Optional[OAuthRunner] = None,
+    onboarding_hook: Optional[OnboardingHook] = None,
+    extras: Optional[Dict[str, Any]] = None,
+) -> None:
+    if project_root is not None:
+        ConfigStore.project_root = Path(project_root)
+    if logger is not None:
+        ConfigStore.logger = logger
+    if oauth is not None:
+        ConfigStore._oauth = {k: v for k, v in oauth.items() if v is not None}
+    if oauth_runner is not None:
+        ConfigStore.oauth_runner = oauth_runner
+    if onboarding_hook is not None:
+        ConfigStore.onboarding_hook = onboarding_hook
+    if extras is not None:
+        ConfigStore.extras = dict(extras)
diff --git a/craftos_integrations/credentials_store.py b/craftos_integrations/credentials_store.py
new file mode 100644
index 00000000..f3f9015b
--- /dev/null
+++ b/craftos_integrations/credentials_store.py
@@ -0,0 +1,133 @@
+"""JSON-file storage in <project_root>/.credentials/.
+
+Two parallel APIs share the same on-disk format and directory:
+
+  - ``save_credential`` / ``load_credential`` / ``has_credential`` /
+    ``remove_credential``: per-integration credentials (auth tokens,
+    access tokens, OAuth refresh tokens, etc.). Files like
+    ``github.json``, ``slack.json``.
+
+  - ``save_config`` / ``load_config`` / ``has_config`` /
+    ``remove_config``: per-integration runtime config (watch tags,
+    channel filters, polling intervals, etc.). Files like
+    ``github_config.json``, ``slack_config.json``.
+
+The two are kept in separate files so saving config never rewrites a
+credential file (less risk for the secret-bearing data, easier diffing,
+clearer mental model). Both use the same JSON-of-dataclass shape.
+
+The directory location comes from ``ConfigStore.project_root``, which the
+host sets via ``configure(project_root=...)``.
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import asdict, fields
+from pathlib import Path
+from typing import Optional, Type, TypeVar
+
+from .config import ConfigStore
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+
+def _credentials_dir() -> Path:
+    path = ConfigStore.project_root / ".credentials"
+    path.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(path, stat.S_IRWXU)
+    except OSError:
+        pass
+    return path
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Internal: shared I/O for both credentials and config
+# ════════════════════════════════════════════════════════════════════════
+
+def _load_dataclass(filename: str, cls: Type[T], kind: str) -> Optional[T]:
+    """Read a JSON file and instantiate ``cls`` with the matching fields.
+
+    Unknown JSON keys are silently dropped (so removing a field from the
+    dataclass doesn't break loading older files). ``kind`` is just a log
+    label ("credential" / "config")."""
+    path = _credentials_dir() / filename
+    if not path.exists():
+        return None
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        valid = {fld.name for fld in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in valid})
+    except Exception as e:
+        logger.warning(f"Failed to load {kind} {filename}: {e}")
+        return None
+
+
+def _save_dataclass(filename: str, obj, kind: str) -> None:
+    """Serialize a dataclass instance to ``.credentials/<filename>``."""
+    path = _credentials_dir() / filename
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(asdict(obj), f, indent=2, default=str)
+        try:
+            os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass
+        logger.info(f"Saved {kind}: {filename}")
+    except Exception as e:
+        logger.error(f"Failed to save {kind} {filename}: {e}")
+
+
+def _remove(filename: str, kind: str) -> bool:
+    path = _credentials_dir() / filename
+    if path.exists():
+        path.unlink()
+        logger.info(f"Removed {kind}: {filename}")
+        return True
+    return False
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Credentials API
+# ════════════════════════════════════════════════════════════════════════
+
+def has_credential(filename: str) -> bool:
+    return (_credentials_dir() / filename).exists()
+
+
+def load_credential(filename: str, credential_cls: Type[T]) -> Optional[T]:
+    return _load_dataclass(filename, credential_cls, "credential")
+
+
+def save_credential(filename: str, credential) -> None:
+    _save_dataclass(filename, credential, "credential")
+
+
+def remove_credential(filename: str) -> bool:
+    return _remove(filename, "credential")
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Config API — same on-disk layout, different filename convention
+# ════════════════════════════════════════════════════════════════════════
+
+def has_config(filename: str) -> bool:
+    return (_credentials_dir() / filename).exists()
+
+
+def load_config(filename: str, config_cls: Type[T]) -> Optional[T]:
+    return _load_dataclass(filename, config_cls, "config")
+
+
+def save_config(filename: str, config) -> None:
+    _save_dataclass(filename, config, "config")
+
+
+def remove_config(filename: str) -> bool:
+    return _remove(filename, "config")
diff --git a/craftos_integrations/helpers/__init__.py b/craftos_integrations/helpers/__init__.py
new file mode 100644
index 00000000..77955882
--- /dev/null
+++ b/craftos_integrations/helpers/__init__.py
@@ -0,0 +1,23 @@
+"""Internal helpers for integration authors.
+
+These are package-internal utilities used by integration files
+(``craftos_integrations/integrations/<name>.py``). They're not part of the
+public consumer API — host applications interact with the package via the
+top-level facade (``configure``, ``initialize_manager``, ``get_handler``, etc.).
+
+Submodules:
+    http: thin wrappers around httpx that handle the standard REST
+          ``status_code → {ok, result} | {error, details}`` envelope shape.
+    result: ``Result`` / ``Ok`` / ``Err`` TypedDict aliases for the envelope —
+            use as return annotations for static type-checking benefits.
+"""
+from .http import arequest, request
+from .result import Err, Ok, Result
+
+__all__ = [
+    "Err",
+    "Ok",
+    "Result",
+    "arequest",
+    "request",
+]
diff --git a/craftos_integrations/helpers/http.py b/craftos_integrations/helpers/http.py
new file mode 100644
index 00000000..b507c7b1
--- /dev/null
+++ b/craftos_integrations/helpers/http.py
@@ -0,0 +1,110 @@
+"""Thin wrappers around httpx for the standard REST envelope.
+
+Most integration clients in this package call REST APIs and translate the
+response into the package's ``{ok: True, result: ...}`` / ``{error: ..., details: ...}``
+envelope. ``request`` (sync) and ``arequest`` (async) handle the full pattern:
+
+  - send the HTTP request via httpx
+  - on a successful status code → wrap the parsed body via ``transform`` (or pass it through)
+  - on any other status → return ``{error: "API error: <code>", details: <body text>}``
+  - on any exception → return ``{error: str(e)}``
+
+Usage in an integration::
+
+    from ..helpers.http import request
+
+    def get_user(self, user_id: str):
+        return request("GET", f"{API_BASE}/users/{user_id}", headers=self._headers())
+
+    def list_users(self, limit: int = 100):
+        return request(
+            "GET", f"{API_BASE}/users",
+            headers=self._headers(),
+            params={"limit": limit},
+            transform=lambda data: {"users": data, "count": len(data)},
+        )
+
+Note: ``arequest`` is implemented as ``asyncio.to_thread(<sync request>)`` rather
+than ``httpx.AsyncClient`` to bypass anyio/sniffio entirely. On Python 3.14
+conda-forge builds inside this host, ``asyncio.current_task()`` can return
+``None`` even inside a running task — anyio then fails with
+``TypeError: cannot create weak reference to 'NoneType' object``. Sync httpx
++ a worker thread sidesteps anyio's task-tracking entirely.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Callable, Dict, Iterable, Optional
+
+import httpx
+
+from .result import Result
+
+_DEFAULT_EXPECTED = (200, 201)
+
+
+def _shape(r: httpx.Response, expected: Iterable[int],
+           transform: Optional[Callable[[Any], Any]]) -> Result:
+    if r.status_code in expected:
+        try:
+            data = r.json()
+        except Exception:
+            data = None
+        if transform is not None:
+            return {"ok": True, "result": transform(data)}
+        return {"ok": True, "result": data if data is not None else {}}
+    return {"error": f"API error: {r.status_code}", "details": r.text}
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    headers: Optional[Dict[str, str]] = None,
+    json: Any = None,
+    params: Optional[Dict[str, Any]] = None,
+    data: Any = None,
+    files: Any = None,
+    expected: Iterable[int] = _DEFAULT_EXPECTED,
+    transform: Optional[Callable[[Any], Any]] = None,
+    timeout: float = 15.0,
+) -> Result:
+    """Sync REST helper. Returns ``{ok, result}`` or ``{error, details}``."""
+    try:
+        r = httpx.request(
+            method, url,
+            headers=headers, json=json, params=params,
+            data=data, files=files, timeout=timeout,
+        )
+        return _shape(r, expected, transform)
+    except Exception as e:
+        return {"error": str(e)}
+
+
+async def arequest(
+    method: str,
+    url: str,
+    *,
+    headers: Optional[Dict[str, str]] = None,
+    json: Any = None,
+    params: Optional[Dict[str, Any]] = None,
+    data: Any = None,
+    files: Any = None,
+    expected: Iterable[int] = _DEFAULT_EXPECTED,
+    transform: Optional[Callable[[Any], Any]] = None,
+    timeout: float = 15.0,
+) -> Result:
+    """Async REST helper. Runs sync httpx in a worker thread to avoid anyio.
+
+    Identical contract to ``request`` — returns ``{ok, result}`` or
+    ``{error, details}``. Awaitable from any coroutine; non-blocking for the
+    event loop because the actual HTTP work happens in the default thread
+    executor via ``asyncio.to_thread``.
+    """
+    return await asyncio.to_thread(
+        request,
+        method, url,
+        headers=headers, json=json, params=params,
+        data=data, files=files,
+        expected=expected, transform=transform, timeout=timeout,
+    )
diff --git a/craftos_integrations/helpers/result.py b/craftos_integrations/helpers/result.py
new file mode 100644
index 00000000..a40bb387
--- /dev/null
+++ b/craftos_integrations/helpers/result.py
@@ -0,0 +1,36 @@
+"""Standard return-envelope types for craftos_integrations.
+
+Most client methods (and the helpers in ``helpers.http``) return one of two shapes:
+
+  - **Success**: ``{"ok": True, "result": <any>}``
+  - **Failure**: ``{"error": <str>, "details": <any>}`` — ``details`` is optional.
+
+These are the runtime shapes — using these aliases as return annotations is a
+type-check hint only, not a runtime check.
+
+Three integrations (Slack, Telegram Bot, Notion) intentionally diverge: their
+file-private call helpers return the raw API body on success so callers can
+read flat fields like ``result["channels"]`` directly. Those still return
+``Dict[str, Any]`` and are documented in their respective files.
+"""
+from __future__ import annotations
+
+from typing import Any, TypedDict, Union
+
+try:
+    from typing import NotRequired  # 3.11+
+except ImportError:
+    from typing_extensions import NotRequired  # type: ignore[assignment]
+
+
+class Ok(TypedDict):
+    ok: bool   # always True for the Ok shape
+    result: Any
+
+
+class Err(TypedDict):
+    error: str
+    details: NotRequired[Any]
+
+
+Result = Union[Ok, Err]
diff --git a/craftos_integrations/integrations/__init__.py b/craftos_integrations/integrations/__init__.py
new file mode 100644
index 00000000..0cd7f6ea
--- /dev/null
+++ b/craftos_integrations/integrations/__init__.py
@@ -0,0 +1,18 @@
+"""Integrations subpackage. Every immediate-child folder (or .py module)
+that doesn't start with ``_`` is autoloaded at startup.
+
+To add a new integration, create a folder ``<name>/`` containing:
+  - ``__init__.py`` with:
+      - a credential dataclass
+      - an IntegrationSpec
+      - an IntegrationHandler subclass decorated with @register_handler
+      - a BasePlatformClient subclass decorated with @register_client
+  - (optional) ``INTEGRATION.md`` documenting the integration
+  - (optional) underscore-prefixed sibling helpers (e.g. ``_bridge_client.py``)
+
+Helpers shared across multiple integrations live at this level with an
+underscore prefix (``_google_common.py``, ``_lark_common.py``) — the
+autoloader skips them.
+
+See github/ for the canonical shape.
+"""
diff --git a/craftos_integrations/integrations/_google_common.py b/craftos_integrations/integrations/_google_common.py
new file mode 100644
index 00000000..4f5c8571
--- /dev/null
+++ b/craftos_integrations/integrations/_google_common.py
@@ -0,0 +1,280 @@
+# -*- coding: utf-8 -*-
+"""Shared Google OAuth scaffolding — used by every Google-service integration.
+
+Underscore prefix → autoloader skips this module. It's package-internal,
+imported by the per-service integrations (``gmail.py``, ``google_calendar.py``,
+``google_drive.py``, ``google_docs.py``, ``google_youtube.py``).
+
+What it provides
+----------------
+
+  - ``GoogleCredential`` — single dataclass shape for every Google service's
+    credential file. All services use the same shape because they all hold
+    the same kind of token; they just differ in *which* file the token is
+    saved to.
+
+  - ``GMAIL_SCOPES``, ``CALENDAR_SCOPES``, ``DRIVE_SCOPES``, ``DOCS_SCOPES``,
+    ``YOUTUBE_SCOPES``, ``USERINFO_SCOPES`` — per-service scope strings.
+    ``ALL_GOOGLE_SCOPES`` is the union (used by the "connect everything"
+    workspace integration).
+
+  - ``make_google_oauth(scopes)`` — factory returning a per-service
+    ``OAuthFlow`` instance. Each handler holds its own; differs from the
+    others only in scope.
+
+  - ``GoogleApiClientMixin`` — composition mixin for per-service clients.
+    Centralizes load-credential / refresh-token / build-auth-headers so each
+    service's Client doesn't duplicate those ~40 lines.
+
+  - ``run_google_login(spec, oauth_flow)`` — shared async login implementation.
+    Each per-service handler's ``login()`` is a one-liner that delegates here.
+
+Composition over inheritance: the per-service Client subclasses
+``BasePlatformClient`` (the package's runtime ABC) AND mixes in
+``GoogleApiClientMixin`` for token plumbing. The Handler holds an
+``OAuthFlow`` instance from ``make_google_oauth`` (composition).
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+from .. import (
+    IntegrationSpec,
+    OAuthFlow,
+    has_credential,
+    load_credential,
+    remove_credential,
+    save_credential,
+)
+from ..config import ConfigStore
+from ..helpers import Result, request as http_request
+from ..logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# OAuth / API URLs
+# ════════════════════════════════════════════════════════════════════════
+
+GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth"
+GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token"
+GOOGLE_USERINFO_URL = "https://www.googleapis.com/oauth2/v2/userinfo"
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Per-service scopes
+# ════════════════════════════════════════════════════════════════════════
+
+# Always requested alongside the service scope so we can populate
+# ``GoogleCredential.email`` from the userinfo endpoint.
+USERINFO_SCOPES = (
+    "https://www.googleapis.com/auth/userinfo.email "
+    "https://www.googleapis.com/auth/userinfo.profile"
+)
+
+GMAIL_SCOPES = "https://www.googleapis.com/auth/gmail.modify"
+CALENDAR_SCOPES = "https://www.googleapis.com/auth/calendar"
+DRIVE_SCOPES = "https://www.googleapis.com/auth/drive"
+DOCS_SCOPES = "https://www.googleapis.com/auth/documents"
+YOUTUBE_SCOPES = (
+    "https://www.googleapis.com/auth/youtube.readonly "
+    "https://www.googleapis.com/auth/youtube.force-ssl"
+)
+CONTACTS_SCOPES = "https://www.googleapis.com/auth/contacts.readonly"
+
+# Union — used by the "connect everything" Workspace integration.
+ALL_GOOGLE_SCOPES = " ".join([
+    GMAIL_SCOPES,
+    CALENDAR_SCOPES,
+    DRIVE_SCOPES,
+    CONTACTS_SCOPES,
+    USERINFO_SCOPES,
+    YOUTUBE_SCOPES,
+])
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Credential dataclass (shared across all Google services)
+# ════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class GoogleCredential:
+    """Shape of every Google service's credential file.
+
+    Each service writes the same shape but to a different file
+    (``gmail.json``, ``gcal.json``, …). When the workspace meta-integration
+    connects, it cascades the same credential into all per-service files.
+    """
+    access_token: str = ""
+    refresh_token: str = ""
+    token_expiry: float = 0.0
+    client_id: str = ""
+    client_secret: str = ""
+    email: str = ""
+
+
+# ════════════════════════════════════════════════════════════════════════
+# OAuthFlow factory — composition for handlers
+# ════════════════════════════════════════════════════════════════════════
+
+def make_google_oauth(scopes: str) -> OAuthFlow:
+    """Build the per-service ``OAuthFlow``. The userinfo scopes are always
+    appended so we can capture the user's email regardless of which service
+    is being connected."""
+    return OAuthFlow(
+        client_id_key="GOOGLE_CLIENT_ID",
+        client_secret_key="GOOGLE_CLIENT_SECRET",
+        auth_url=GOOGLE_AUTH_URL,
+        token_url=GOOGLE_TOKEN_URL,
+        userinfo_url=GOOGLE_USERINFO_URL,
+        scopes=f"{scopes} {USERINFO_SCOPES}".strip(),
+        use_pkce=True,
+        extra_auth_params={"access_type": "offline", "prompt": "consent"},
+    )
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Shared login / logout / status helpers — called by per-service handlers
+# ════════════════════════════════════════════════════════════════════════
+
+async def run_google_login(
+    spec: IntegrationSpec,
+    oauth: OAuthFlow,
+    display_name: str,
+) -> Tuple[bool, str]:
+    """Run the OAuth flow and persist the credential to the spec's file.
+    Each per-service handler's ``login()`` calls into this — one place to
+    change if Google ever changes the auth shape."""
+    result = await oauth.run()
+    if "error" in result and not result.get("access_token"):
+        return False, f"{display_name} OAuth failed: {result['error']}"
+
+    info = result.get("userinfo", {})
+    save_credential(spec.cred_file, GoogleCredential(
+        access_token=result["access_token"],
+        refresh_token=result.get("refresh_token", ""),
+        token_expiry=time.time() + result.get("expires_in", 3600),
+        client_id=ConfigStore.get_oauth("GOOGLE_CLIENT_ID"),
+        client_secret=ConfigStore.get_oauth("GOOGLE_CLIENT_SECRET"),
+        email=info.get("email", ""),
+    ))
+    return True, f"{display_name} connected as {info.get('email')}"
+
+
+async def run_google_logout(
+    spec: IntegrationSpec,
+    display_name: str,
+) -> Tuple[bool, str]:
+    """Standard logout: just remove the credential file. Server-side
+    invalidation isn't necessary for Google — the refresh token expires
+    naturally and access tokens are short-lived."""
+    if not has_credential(spec.cred_file):
+        return False, f"No {display_name} credentials found."
+    remove_credential(spec.cred_file)
+    return True, f"Removed {display_name} credential."
+
+
+async def run_google_status(
+    spec: IntegrationSpec,
+    display_name: str,
+) -> Tuple[bool, str]:
+    """Standard status: connected/not-connected based on credential file."""
+    if not has_credential(spec.cred_file):
+        return True, f"{display_name}: Not connected"
+    cred = load_credential(spec.cred_file, GoogleCredential)
+    email = cred.email if cred else "unknown"
+    return True, f"{display_name}: Connected\n  - {email}"
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Client mixin — shared token plumbing for every per-service Client
+# ════════════════════════════════════════════════════════════════════════
+
+class GoogleApiClientMixin:
+    """Composition mixin: gives a Client class the shared Google token
+    machinery (load credential, refresh on expiry, build auth headers).
+
+    Used by the per-service Clients alongside ``BasePlatformClient``::
+
+        class GmailClient(BasePlatformClient, GoogleApiClientMixin):
+            spec = GMAIL_SPEC
+            ...
+
+    The mixin reads ``self.spec`` (set by the subclass) to know which
+    credential file to load. No state is kept on the mixin itself; every
+    method reads/writes through ``self._cred`` on the subclass instance.
+    """
+    spec: IntegrationSpec  # subclass provides this
+    _cred: Optional[GoogleCredential]  # subclass declares in __init__
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> GoogleCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, GoogleCredential)
+        if self._cred is None:
+            raise RuntimeError(
+                f"No {self.spec.name} credentials. Connect the integration first."
+            )
+        return self._cred
+
+    def _ensure_token(self) -> str:
+        cred = self._load()
+        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
+            refreshed = self.refresh_access_token()
+            if refreshed:
+                return refreshed
+        return cred.access_token
+
+    def refresh_access_token(self) -> Optional[str]:
+        cred = self._load()
+        if not all([cred.client_id, cred.client_secret, cred.refresh_token]):
+            return None
+        result = http_request("POST", GOOGLE_TOKEN_URL, data={
+            "client_id": cred.client_id,
+            "client_secret": cred.client_secret,
+            "refresh_token": cred.refresh_token,
+            "grant_type": "refresh_token",
+        }, expected=(200,))
+        if "error" in result:
+            return None
+        data = result["result"]
+        cred.access_token = data["access_token"]
+        cred.token_expiry = time.time() + data.get("expires_in", 3600) - 60
+        save_credential(self.spec.cred_file, cred)
+        self._cred = cred
+        return cred.access_token
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._ensure_token()}",
+            "Content-Type": "application/json",
+        }
+
+    def _auth_header(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._ensure_token()}"}
+
+
+__all__ = [
+    "GoogleCredential",
+    "GoogleApiClientMixin",
+    "GOOGLE_AUTH_URL",
+    "GOOGLE_TOKEN_URL",
+    "GOOGLE_USERINFO_URL",
+    "USERINFO_SCOPES",
+    "GMAIL_SCOPES",
+    "CALENDAR_SCOPES",
+    "DRIVE_SCOPES",
+    "DOCS_SCOPES",
+    "YOUTUBE_SCOPES",
+    "CONTACTS_SCOPES",
+    "ALL_GOOGLE_SCOPES",
+    "make_google_oauth",
+    "run_google_login",
+    "run_google_logout",
+    "run_google_status",
+]
diff --git a/craftos_integrations/integrations/_lark_common.py b/craftos_integrations/integrations/_lark_common.py
new file mode 100644
index 00000000..542c3b46
--- /dev/null
+++ b/craftos_integrations/integrations/_lark_common.py
@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""Shared Lark scaffolding — used by every Lark-service integration.
+
+Underscore prefix → autoloader skips this module. It's package-internal,
+imported by ``lark.py`` (messaging) and ``lark_drive.py``, with future
+siblings (calendar, docs, bitable, …) following the same shape.
+
+What it provides
+----------------
+
+  - ``LarkCredential`` — single dataclass shape for every Lark service's
+    credential file. All services share the same shape because all use
+    the same Custom App's App ID + Secret + cached tenant_access_token.
+    Bot-specific fields (``bot_name``, ``bot_open_id``) are populated
+    only by the messaging integration; non-messaging services leave
+    them empty.
+
+  - ``LARK_API_BASE`` — the global Lark host. Feishu (China region)
+    differs only in this constant; the API surface is identical.
+
+  - ``validate_and_mint_token(app_id, app_secret)`` — one-shot credential
+    validation used by every handler's ``login()``. Returns
+    ``(token, expires_at, error)``.
+
+  - ``ensure_token(cred, cred_file)`` — refresh-if-needed token getter.
+    Mutates ``cred`` in place and persists to ``cred_file`` when a
+    refresh actually happens. Each service holds its own credential
+    file with its own cached token (no cross-service sharing).
+
+  - ``make_headers(cred, cred_file)`` — bearer + JSON content-type. All
+    Lark REST calls use this shape.
+
+Why a separate file per service uses its own credential file
+-------------------------------------------------------------
+
+Even though every Lark service is authorized via the *same* Custom App,
+the user wires each service as a sibling integration in the registry
+(matches the ``google_*.py`` pattern). Each gets its own ``IntegrationSpec``
+with its own ``cred_file`` so that connect/disconnect status is
+per-service in the UI. The user pastes the same App ID + Secret into
+each one — slight UX redundancy, paid back in clean independence
+between services.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Dict, Optional, Tuple
+
+from .. import save_credential
+from ..helpers import request as http_request
+
+LARK_API_BASE = "https://open.larksuite.com/open-apis"
+
+
+@dataclass
+class LarkCredential:
+    app_id: str = ""
+    app_secret: str = ""
+    # Cached tenant_access_token + its absolute Unix expiry. Saved so we
+    # don't mint a new token on every restart, but always refresh when
+    # within 60s of expiry (defensive — Lark's clocks vs ours).
+    tenant_access_token: str = ""
+    token_expires_at: float = 0.0
+    # Bot-specific (messaging integration only). Non-messaging services
+    # leave these empty; they're carried in the shared shape so that
+    # ``credentials_store._load_dataclass`` survives schema reads of
+    # files written by either kind of handler.
+    bot_name: str = ""
+    bot_open_id: str = ""
+
+
+def validate_and_mint_token(app_id: str, app_secret: str) -> Tuple[Optional[str], float, Optional[str]]:
+    """Validate App ID + Secret by minting a tenant_access_token.
+
+    Returns ``(token, expires_at_unix, error_msg)``. On success, ``error_msg``
+    is None. Lark returns 200 OK with ``code != 0`` on bad credentials, so
+    we have to inspect the body — HTTP status alone isn't enough.
+    """
+    result = http_request(
+        "POST", f"{LARK_API_BASE}/auth/v3/tenant_access_token/internal",
+        json={"app_id": app_id, "app_secret": app_secret},
+        expected=(200,),
+    )
+    if "error" in result:
+        return None, 0.0, f"Lark auth request failed: {result['error']}"
+    body = result.get("result", {})
+    if body.get("code", -1) != 0:
+        return None, 0.0, f"Invalid Lark credentials: {body.get('msg', 'unknown error')}"
+    token = body.get("tenant_access_token", "")
+    expire = float(body.get("expire", 0))
+    return token, time.time() + expire, None
+
+
+def ensure_token(cred: LarkCredential, cred_file: str) -> str:
+    """Return a valid tenant_access_token, refreshing if within 60s of expiry.
+
+    Mutates ``cred`` and writes it back to ``cred_file`` on refresh, so
+    sibling processes / restarts reuse the cached token instead of minting
+    fresh on every call.
+    """
+    now = time.time()
+    if cred.tenant_access_token and cred.token_expires_at > now + 60:
+        return cred.tenant_access_token
+    result = http_request(
+        "POST", f"{LARK_API_BASE}/auth/v3/tenant_access_token/internal",
+        json={"app_id": cred.app_id, "app_secret": cred.app_secret},
+        expected=(200,),
+    )
+    if "error" in result:
+        raise RuntimeError(f"Lark token refresh failed: {result['error']}")
+    body = result.get("result", {})
+    if body.get("code", -1) != 0:
+        raise RuntimeError(f"Lark token refresh rejected: {body.get('msg', 'unknown')}")
+    token = body.get("tenant_access_token", "")
+    expire = float(body.get("expire", 0))
+    cred.tenant_access_token = token
+    cred.token_expires_at = now + expire
+    save_credential(cred_file, cred)
+    return token
+
+
+def make_headers(cred: LarkCredential, cred_file: str) -> Dict[str, str]:
+    """Bearer + JSON content-type. Used by every Lark REST call."""
+    return {
+        "Authorization": f"Bearer {ensure_token(cred, cred_file)}",
+        "Content-Type": "application/json; charset=utf-8",
+    }
diff --git a/craftos_integrations/integrations/discord/INTEGRATION.md b/craftos_integrations/integrations/discord/INTEGRATION.md
new file mode 100644
index 00000000..46c532b1
--- /dev/null
+++ b/craftos_integrations/integrations/discord/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Discord — Integration Reference
+
+Bot integration for messages, threads, reactions, voice, moderation. Talks to Discord's REST + Gateway via a bot token.
+
+## Essentials
+
+- **Send target format matters and varies by action:** `send_discord_message` uses `to: "channel:<id>"` for channels and `to: "user:<id>"` for DMs. Other actions (`add_discord_reaction`, `get_discord_messages`, `editMessage`) take `channelId` directly. Don't mix the two — passing a raw channel ID to `send_discord_message`'s `to` will fail silently or hit the wrong target.
+- **Channel IDs are 18-digit snowflakes** (numeric strings, NOT names). Use `list_discord_guilds` then `get_discord_channels` to translate a channel name to its ID before sending.
+- **DMs require a known DM channel ID,** not a user ID directly. Use `get_discord_user_dm_channels` to look one up, or `send_discord_dm`/`send_discord_user_dm` which handle the lookup internally.
+- **Session-level facts the integration knows:** `bot_id`, `bot_username`. Use introspection rather than asking the user.
+- **`mention_only=True` config:** if set, the bot only processes incoming messages where it is @-mentioned. If incoming events aren't arriving, check this flag.
+- **Permissions:** Discord enforces per-channel perms server-side. A `Missing Access` error means the bot isn't in the guild or lacks scopes — direct the user to the OAuth invite URL. Retrying won't help.
diff --git a/craftos_integrations/integrations/discord/__init__.py b/craftos_integrations/integrations/discord/__init__.py
new file mode 100644
index 00000000..21390070
--- /dev/null
+++ b/craftos_integrations/integrations/discord/__init__.py
@@ -0,0 +1,800 @@
+# -*- coding: utf-8 -*-
+"""Discord integration - bot + user account + voice (lazy)."""
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass, field
+import time
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import quote as _url_quote
+
+import httpx
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+DISCORD_API_BASE = "https://discord.com/api/v10"
+DISCORD_GATEWAY_URL = "wss://gateway.discord.gg/?v=10&encoding=json"
+GATEWAY_INTENTS = (1 << 9) | (1 << 12) | (1 << 15)  # 37376
+
+
+@dataclass
+class DiscordCredential:
+    bot_token: str = ""
+    user_token: str = ""
+    bot_id: str = ""
+    bot_username: str = ""
+
+
+@dataclass
+class DiscordConfig:
+    """Runtime knobs persisted to ``discord_config.json``.
+
+    Two-tier permission model:
+
+    * **Third-party** lists - users/roles whose messages reach the agent as
+      incoming external chatter (``raw.is_self_message = False``). Use for
+      letting a server's general members @-the-bot for help.
+    * **Self** lists - users/roles whose messages reach the agent as if the
+      bot owner sent them (``raw.is_self_message = True``). Use for trusted
+      admins who can drive the bot like its owner - issue commands, change
+      settings, etc.
+
+    Filter behaviour:
+
+    * If ``mention_only`` is set, the bot must be @-mentioned regardless of
+      the lists below.
+    * Self matches always win over third-party matches.
+    * If **all four** allow lists are empty, the filter is fully open and
+      every message is classified as third-party (current default).
+    * If any list has entries, users matching neither list are dropped.
+    """
+    # When True, the bot only forwards messages where it was @-mentioned.
+    # Default False = the bot processes every message it can see in any
+    # channel/guild it's a member of.
+    mention_only: bool = False
+
+    # ----- Third-party allowlist (forwarded as external messages) -----
+    # Comma-separated Discord usernames / display names. Matched
+    # case-insensitively against both ``author.username`` and
+    # ``author.global_name``. Empty = skip this sub-check.
+    third_party_usernames: List[str] = field(default_factory=list)
+    # Comma-separated guild role names. Resolved against the guild's role
+    # list (cached 10 min per guild). Empty = skip this sub-check.
+    # No effect on DMs (no guild context).
+    third_party_role_names: List[str] = field(default_factory=list)
+
+    # ----- Self allowlist (forwarded as if the bot owner sent them) -----
+    # Same matching semantics as the third-party fields above.
+    self_usernames: List[str] = field(default_factory=list)
+    self_role_names: List[str] = field(default_factory=list)
+
+
+DISCORD = IntegrationSpec(
+    name="discord",
+    cred_class=DiscordCredential,
+    cred_file="discord.json",
+    platform_id="discord",
+)
+
+
+def _discord_config_file() -> str:
+    """``discord.json`` → ``discord_config.json``."""
+    stem = DISCORD.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(DISCORD.name)
+class DiscordHandler(IntegrationHandler):
+    spec = DISCORD
+    display_name = "Discord"
+    description = "Community chat"
+    auth_type = "token"
+    icon = "discord"
+    connect_help = [
+        "Open Discord Developer Portal: discord.com/developers/applications",
+        "Click 'New Application' and give it a name",
+        "Open the 'Bot' tab in the left sidebar",
+        "Click 'Reset Token' (or 'Copy' if it's already shown)",
+        "Paste the bot token into the field below",
+    ]
+    fields = [
+        {"key": "bot_token", "label": "Bot Token", "placeholder": "Enter bot token", "password": True},
+    ]
+
+    config_class = DiscordConfig
+    config_fields = [
+        {"key": "mention_only", "label": "Only when @-mentioned", "type": "checkbox",
+         "help": "When on, the bot only forwards messages where it's directly @-mentioned. "
+                 "When off, every message in every channel the bot can see is considered."},
+        {"key": "third_party_usernames", "label": "Third-party users", "type": "list",
+         "placeholder": "alice, bob.s",
+         "help": "Their messages reach the agent as external incoming messages. "
+                 "Comma-separated Discord usernames/display names, case-insensitive. "
+                 "Leave empty to skip this sub-check."},
+        {"key": "third_party_role_names", "label": "Third-party roles", "type": "list",
+         "placeholder": "Member, Contributor",
+         "help": "Same as Third-party users, but matched on Discord role names in the "
+                 "message's guild. DMs ignore this list. Leave empty to skip."},
+        {"key": "self_usernames", "label": "Self users", "type": "list",
+         "placeholder": "ahmad",
+         "help": "Their messages are treated as if you (the bot owner) sent them - used "
+                 "for trusted admins who can drive the bot like its owner. Self matches "
+                 "win over third-party matches. Leave empty to skip."},
+        {"key": "self_role_names", "label": "Self roles", "type": "list",
+         "placeholder": "Admin, Owner",
+         "help": "Same as Self users, but matched on role names. DMs ignore this list. "
+                 "Leave empty to skip. Note: if all four allow lists are empty, the filter "
+                 "is fully open and every message is treated as third-party (default)."},
+    ]
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["login", "logout", "status"]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, "Usage: /discord login <bot_token>"
+        bot_token = args[0]
+        try:
+            r = httpx.get(
+                "https://discord.com/api/v10/users/@me",
+                headers={"Authorization": f"Bot {bot_token}"},
+                timeout=15,
+            )
+            if r.status_code != 200:
+                return False, f"Invalid bot token: {r.status_code}"
+            data = r.json()
+        except Exception as e:
+            return False, f"Discord connection error: {e}"
+
+        save_credential(self.spec.cred_file, DiscordCredential(
+            bot_token=bot_token,
+            bot_id=str(data.get("id") or ""),
+            bot_username=data.get("username") or "",
+        ))
+        return True, f"Discord bot connected: {data.get('username')} ({data.get('id')})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Discord credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Discord credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Discord: Not connected"
+        cred = load_credential(self.spec.cred_file, DiscordCredential)
+        if not cred or not cred.bot_token:
+            return True, "Discord: Not connected"
+        # Emit a parseable account row so the Manage modal's "Connected
+        # Accounts" section populates. Falls back to the literal "bot" if
+        # we don't have the cached username/id (older creds pre-migration).
+        name = cred.bot_username or "Discord bot"
+        ident = cred.bot_id or "bot"
+        return True, f"Discord: Connected\n  - {name} ({ident})"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class DiscordClient(BasePlatformClient):
+    """Unified Discord client exposing bot, user, and voice operations."""
+    spec = DISCORD
+    PLATFORM_ID = DISCORD.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[DiscordCredential] = None
+        self._ws = None
+        self._ws_task: Optional[asyncio.Task] = None
+        self._heartbeat_task: Optional[asyncio.Task] = None
+        self._heartbeat_interval: float = 41.25
+        self._last_sequence: Optional[int] = None
+        self._bot_user_id: Optional[str] = None
+        self._catchup_done: bool = False
+        # Lazy voice manager - created/started on first voice call, reused after
+        self._voice_mgr: Optional[Any] = None
+        # Per-guild role-name cache: guild_id -> ({role_id: lower_name}, expires_at).
+        # Refreshed on miss / 10-minute expiry so role renames or new roles
+        # propagate without an agent restart.
+        self._role_name_cache: Dict[str, Tuple[Dict[str, str], float]] = {}
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> DiscordCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, DiscordCredential)
+        if self._cred is None:
+            raise RuntimeError("No Discord credentials. Use /discord login first.")
+        return self._cred
+
+    def _bot_token(self) -> str:
+        cred = self._load()
+        if not cred.bot_token:
+            raise RuntimeError("No Discord bot_token configured.")
+        return cred.bot_token
+
+    def _user_token(self) -> str:
+        cred = self._load()
+        if not cred.user_token:
+            raise RuntimeError("No Discord user_token configured.")
+        return cred.user_token
+
+    def _bot_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bot {self._bot_token()}", "Content-Type": "application/json"}
+
+    def _user_headers(self) -> Dict[str, str]:
+        return {"Authorization": self._user_token(), "Content-Type": "application/json"}
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        cred = self._load()
+        if not cred.bot_token:
+            raise RuntimeError("No Discord bot token for Gateway connection")
+
+        bot_info = self.get_bot_user()
+        if "error" in bot_info:
+            raise RuntimeError(f"Invalid Discord bot token: {bot_info.get('error')}")
+        self._bot_user_id = bot_info["result"]["id"]
+
+        self._listening = True
+        self._catchup_done = False
+        self._ws_task = asyncio.create_task(self._gateway_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._heartbeat_task and not self._heartbeat_task.done():
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+        self._heartbeat_task = None
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+        if self._ws_task and not self._ws_task.done():
+            self._ws_task.cancel()
+            try:
+                await self._ws_task
+            except asyncio.CancelledError:
+                pass
+        self._ws_task = None
+
+    async def _gateway_loop(self) -> None:
+        import websockets
+        while self._listening:
+            try:
+                async with websockets.connect(
+                    DISCORD_GATEWAY_URL,
+                    open_timeout=None,
+                    ping_interval=None,
+                    ping_timeout=None,
+                    close_timeout=None,
+                ) as ws:
+                    self._ws = ws
+                    await self._handle_gateway(ws)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[DISCORD] Gateway error: {e}")
+                if self._listening:
+                    await asyncio.sleep(5)
+
+    async def _handle_gateway(self, ws) -> None:
+        try:
+            async for raw in ws:
+                if not self._listening:
+                    break
+                try:
+                    data = json.loads(raw)
+                    await self._process_gateway_event(ws, data)
+                except Exception as e:
+                    logger.error(f"[DISCORD] Error processing Gateway event: {e}")
+        except Exception as e:
+            logger.debug(f"[DISCORD] Gateway socket closed: {e}")
+
+    async def _process_gateway_event(self, ws, data: dict) -> None:
+        op = data.get("op")
+        t = data.get("t")
+        d = data.get("d")
+        s = data.get("s")
+        if s is not None:
+            self._last_sequence = s
+
+        if op == 10:
+            self._heartbeat_interval = d["heartbeat_interval"] / 1000.0
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop(ws))
+            await ws.send(json.dumps({
+                "op": 2,
+                "d": {
+                    "token": self._bot_token(),
+                    "intents": GATEWAY_INTENTS,
+                    "properties": {"os": "windows", "browser": "craftosbot", "device": "craftosbot"},
+                },
+            }))
+        elif op == 0:
+            if t == "READY":
+                asyncio.get_running_loop().call_later(2.0, self._mark_catchup_done)
+            elif t == "MESSAGE_CREATE" and d:
+                await self._handle_message_create(d)
+        elif op == 1:
+            await ws.send(json.dumps({"op": 1, "d": self._last_sequence}))
+        elif op in (7, 9):
+            # 7 = reconnect requested, 9 = invalid session - both close the socket
+            await ws.close()
+
+    def _mark_catchup_done(self) -> None:
+        self._catchup_done = True
+
+    async def _heartbeat_loop(self, ws) -> None:
+        try:
+            while self._listening:
+                await ws.send(json.dumps({"op": 1, "d": self._last_sequence}))
+                await asyncio.sleep(self._heartbeat_interval)
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            pass
+
+    async def _handle_message_create(self, d: dict) -> None:
+        author = d.get("author", {})
+        if author.get("id") == self._bot_user_id or author.get("bot"):
+            return
+        content = d.get("content", "")
+        if not content or not self._catchup_done:
+            return
+
+        # ----- Filter + classify -----
+        # Two-stage:
+        #   1. mention_only - drop if bot wasn't @-mentioned (when enabled)
+        #   2. allowlists - try self first; if matched, classify as
+        #      ``is_self_message=True``. Else try third-party. If neither
+        #      list matches AND any list is configured, drop. If all four
+        #      lists are empty, the filter is fully open (current default).
+        cfg = load_config(_discord_config_file(), DiscordConfig) or DiscordConfig()
+
+        if cfg.mention_only:
+            mentions = d.get("mentions") or []
+            mentioned_ids = {str(m.get("id")) for m in mentions if isinstance(m, dict)}
+            if self._bot_user_id and self._bot_user_id not in mentioned_ids:
+                return
+
+        guild_id = d.get("guild_id")
+        member = d.get("member") or {}
+        role_ids = [str(r) for r in (member.get("roles") or [])]
+        author_username_candidates = {
+            (author.get("username") or "").lower(),
+            (author.get("global_name") or "").lower(),
+        }
+        # Resolve role names lazily - only fetch if any role list is set.
+        # Cached 10 min per guild, async helper takes a thread off the event loop.
+        user_role_names: set = set()
+        any_role_list = (cfg.self_role_names or cfg.third_party_role_names)
+        if any_role_list and guild_id and role_ids:
+            role_map = await self._resolve_guild_role_names(str(guild_id))
+            user_role_names = {role_map.get(rid, "") for rid in role_ids if role_map.get(rid)}
+
+        def _matches(usernames: list, role_names: list) -> bool:
+            uns = {u.lower().strip() for u in (usernames or []) if u.strip()}
+            rns = {r.lower().strip() for r in (role_names or []) if r.strip()}
+            if uns and any(c and c in uns for c in author_username_candidates):
+                return True
+            if rns and user_role_names and (rns & user_role_names):
+                return True
+            return False
+
+        any_self = bool(cfg.self_usernames or cfg.self_role_names)
+        any_tp = bool(cfg.third_party_usernames or cfg.third_party_role_names)
+
+        is_self_message = False
+        if any_self and _matches(cfg.self_usernames, cfg.self_role_names):
+            is_self_message = True
+        elif any_tp and _matches(cfg.third_party_usernames, cfg.third_party_role_names):
+            is_self_message = False
+        elif any_self or any_tp:
+            # At least one list configured but the user matched none → drop.
+            return
+        # else: all four lists empty → fall through, classify as third-party.
+
+        author_name = author.get("username", "Unknown")
+        channel_id = d.get("channel_id", "")
+        guild_id = d.get("guild_id", "")
+        channel_name = f"#{channel_id}" if guild_id else "DM"
+
+        ts = None
+        try:
+            ts = datetime.fromisoformat(d.get("timestamp", ""))
+        except Exception:
+            pass
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=author.get("id", ""),
+                sender_name=author_name,
+                text=content,
+                channel_id=channel_id,
+                channel_name=channel_name,
+                message_id=d.get("id", ""),
+                timestamp=ts,
+                raw={"guild_id": guild_id, "is_self_message": is_self_message},
+            ))
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return self.bot_send_message(channel_id=recipient, content=text, **kwargs)
+
+    # ----- Bot REST API -----
+    def get_bot_user(self) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me",
+            headers=self._bot_headers(),
+            transform=lambda d: {
+                "id": d.get("id"), "username": d.get("username"),
+                "discriminator": d.get("discriminator"), "avatar": d.get("avatar"),
+                "bot": d.get("bot", True),
+            },
+        )
+
+    def get_bot_guilds(self, limit: int = 100) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me/guilds",
+            headers=self._bot_headers(), params={"limit": limit},
+            transform=lambda d: {"guilds": d},
+        )
+
+    def get_guild_channels(self, guild_id: str) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/guilds/{guild_id}/channels",
+            headers=self._bot_headers(),
+            transform=lambda channels: {
+                "all_channels": channels,
+                "text_channels": [c for c in channels if c.get("type") == 0],
+                "voice_channels": [c for c in channels if c.get("type") == 2],
+                "categories": [c for c in channels if c.get("type") == 4],
+            },
+        )
+
+    def get_guild_roles(self, guild_id: str) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/guilds/{guild_id}/roles",
+            headers=self._bot_headers(), expected=(200,),
+            transform=lambda roles: {"roles": roles},
+        )
+
+    async def _resolve_guild_role_names(self, guild_id: str) -> Dict[str, str]:
+        """Return ``{role_id: lower-cased role_name}`` for ``guild_id``, cached 10 min.
+
+        Used by the listener's role-name allowlist filter. Falls back to an
+        empty mapping on REST failure so a transient API blip doesn't lock
+        the agent out of its own messages - the role check is bypassed in
+        that case (handled by the caller).
+        """
+        now = time.time()
+        cached = self._role_name_cache.get(guild_id)
+        if cached and cached[1] > now:
+            return cached[0]
+        try:
+            result = await asyncio.to_thread(self.get_guild_roles, guild_id)
+            roles = result.get("result", {}).get("roles", []) if "error" not in result else []
+            mapping = {str(r.get("id")): (r.get("name") or "").lower()
+                       for r in roles if isinstance(r, dict)}
+        except Exception as e:
+            logger.debug(f"[DISCORD] role lookup for {guild_id} failed: {e}")
+            mapping = {}
+        self._role_name_cache[guild_id] = (mapping, now + 600.0)
+        return mapping
+
+    def get_channel(self, channel_id: str) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/channels/{channel_id}",
+            headers=self._bot_headers(),
+        )
+
+    def bot_send_message(self, channel_id: str, content: str,
+                         embed: Optional[Dict[str, Any]] = None,
+                         reply_to: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"content": content}
+        if embed:
+            payload["embeds"] = [embed]
+        if reply_to:
+            payload["message_reference"] = {"message_id": reply_to}
+        return http_request(
+            "POST", f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
+            headers=self._bot_headers(), json=payload,
+            transform=lambda d: {
+                "message_id": d.get("id"), "channel_id": d.get("channel_id"),
+                "content": d.get("content"), "timestamp": d.get("timestamp"),
+            },
+        )
+
+    def get_messages(self, channel_id: str, limit: int = 50,
+                     before: Optional[str] = None, after: Optional[str] = None) -> Result:
+        params: Dict[str, Any] = {"limit": min(limit, 100)}
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
+            headers=self._bot_headers(), params=params, expected=(200,),
+            transform=lambda messages: {
+                "messages": [
+                    {"id": m.get("id"), "content": m.get("content"),
+                     "author": {"id": m.get("author", {}).get("id"),
+                                "username": m.get("author", {}).get("username"),
+                                "bot": m.get("author", {}).get("bot", False)},
+                     "timestamp": m.get("timestamp"),
+                     "attachments": m.get("attachments", []),
+                     "embeds": m.get("embeds", [])}
+                    for m in messages
+                ],
+                "count": len(messages),
+            },
+        )
+
+    def edit_message(self, channel_id: str, message_id: str, content: str) -> Result:
+        return http_request(
+            "PATCH", f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}",
+            headers=self._bot_headers(), json={"content": content}, expected=(200,),
+        )
+
+    def delete_message(self, channel_id: str, message_id: str) -> Result:
+        return http_request(
+            "DELETE", f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}",
+            headers=self._bot_headers(), expected=(204,),
+            transform=lambda _: {"deleted": True},
+        )
+
+    def create_dm_channel(self, recipient_id: str) -> Result:
+        return http_request(
+            "POST", f"{DISCORD_API_BASE}/users/@me/channels",
+            headers=self._bot_headers(), json={"recipient_id": recipient_id},
+            transform=lambda d: {
+                "channel_id": d.get("id"), "type": d.get("type"),
+                "recipients": d.get("recipients", []),
+            },
+        )
+
+    def send_dm(self, recipient_id: str, content: str,
+                embed: Optional[Dict[str, Any]] = None) -> Result:
+        dm_result = self.create_dm_channel(recipient_id)
+        if "error" in dm_result:
+            return dm_result
+        return self.bot_send_message(dm_result["result"]["channel_id"], content, embed)
+
+    def get_user(self, user_id: str) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/{user_id}",
+            headers=self._bot_headers(), expected=(200,),
+        )
+
+    def get_guild_member(self, guild_id: str, user_id: str) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/guilds/{guild_id}/members/{user_id}",
+            headers=self._bot_headers(), expected=(200,),
+        )
+
+    def list_guild_members(self, guild_id: str, limit: int = 100) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/guilds/{guild_id}/members",
+            headers=self._bot_headers(), params={"limit": min(limit, 1000)}, expected=(200,),
+            transform=lambda members: {"members": members},
+        )
+
+    def add_reaction(self, channel_id: str, message_id: str, emoji: str) -> Result:
+        encoded_emoji = _url_quote(emoji, safe="")
+        return http_request(
+            "PUT",
+            f"{DISCORD_API_BASE}/channels/{channel_id}/messages/{message_id}/reactions/{encoded_emoji}/@me",
+            headers=self._bot_headers(), expected=(204,),
+            transform=lambda _: {"added": True, "emoji": emoji},
+        )
+
+    # ----- User-account methods -----
+    def user_get_current_user(self) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me",
+            headers=self._user_headers(), expected=(200,),
+            transform=lambda d: {
+                "id": d.get("id"), "username": d.get("username"),
+                "discriminator": d.get("discriminator"), "email": d.get("email"),
+                "avatar": d.get("avatar"),
+            },
+        )
+
+    def user_get_guilds(self, limit: int = 100) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me/guilds",
+            headers=self._user_headers(), params={"limit": limit}, expected=(200,),
+            transform=lambda d: {"guilds": d},
+        )
+
+    def user_get_dm_channels(self) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me/channels",
+            headers=self._user_headers(), expected=(200,),
+            transform=lambda channels: {
+                "dm_channels": [
+                    {"id": c.get("id"), "type": c.get("type"),
+                     "recipients": [{"id": rec.get("id"), "username": rec.get("username")}
+                                    for rec in c.get("recipients", [])],
+                     "last_message_id": c.get("last_message_id")}
+                    for c in channels
+                ],
+                "count": len(channels),
+            },
+        )
+
+    def user_send_message(self, channel_id: str, content: str,
+                          reply_to: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"content": content}
+        if reply_to:
+            payload["message_reference"] = {"message_id": reply_to}
+        return http_request(
+            "POST", f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
+            headers=self._user_headers(), json=payload,
+            transform=lambda d: {
+                "message_id": d.get("id"), "channel_id": d.get("channel_id"),
+                "content": d.get("content"), "timestamp": d.get("timestamp"),
+            },
+        )
+
+    def user_get_messages(self, channel_id: str, limit: int = 50,
+                          before: Optional[str] = None, after: Optional[str] = None) -> Result:
+        params: Dict[str, Any] = {"limit": min(limit, 100)}
+        if before:
+            params["before"] = before
+        if after:
+            params["after"] = after
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/channels/{channel_id}/messages",
+            headers=self._user_headers(), params=params, expected=(200,),
+            transform=lambda messages: {
+                "messages": [
+                    {"id": m.get("id"), "content": m.get("content"),
+                     "author": {"id": m.get("author", {}).get("id"),
+                                "username": m.get("author", {}).get("username")},
+                     "timestamp": m.get("timestamp"),
+                     "attachments": m.get("attachments", [])}
+                    for m in messages
+                ],
+                "count": len(messages),
+            },
+        )
+
+    def user_send_dm(self, recipient_id: str, content: str) -> Result:
+        result = http_request(
+            "POST", f"{DISCORD_API_BASE}/users/@me/channels",
+            headers=self._user_headers(), json={"recipient_id": recipient_id},
+        )
+        if "error" in result:
+            return result
+        channel_id = result.get("result", {}).get("id")
+        return self.user_send_message(channel_id, content)
+
+    def user_get_relationships(self) -> Result:
+        def _shape(relationships):
+            friends = [r for r in relationships if r.get("type") == 1]
+            return {
+                "friends": [{"id": r.get("id"),
+                             "username": r.get("user", {}).get("username")} for r in friends],
+                "blocked": [r for r in relationships if r.get("type") == 2],
+                "incoming_requests": [r for r in relationships if r.get("type") == 3],
+                "outgoing_requests": [r for r in relationships if r.get("type") == 4],
+                "total_friends": len(friends),
+            }
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/users/@me/relationships",
+            headers=self._user_headers(), expected=(200,), transform=_shape,
+        )
+
+    def user_search_guild_messages(self, guild_id: str, query: str, limit: int = 25) -> Result:
+        return http_request(
+            "GET", f"{DISCORD_API_BASE}/guilds/{guild_id}/messages/search",
+            headers=self._user_headers(),
+            params={"content": query, "limit": limit}, expected=(200,), timeout=30,
+            transform=lambda d: {
+                "total_results": d.get("total_results"),
+                "messages": d.get("messages", []),
+            },
+        )
+
+    # ----- Voice (lazy import + cached manager) -----
+    async def _voice_manager(self):
+        """Lazy-create + start the DiscordVoiceManager once and reuse it.
+
+        Previous behaviour created a fresh manager + started a new bot
+        connection on every voice call, leaking connections.
+        """
+        if self._voice_mgr is None:
+            from . import _discord_voice
+            self._voice_mgr = _discord_voice.DiscordVoiceManager(self._bot_token())
+        if not getattr(self._voice_mgr, "_running", False):
+            await self._voice_mgr.start()
+        return self._voice_mgr
+
+    async def join_voice(self, guild_id: str, channel_id: str,
+                         self_deaf: bool = False, self_mute: bool = False) -> Result:
+        try:
+            mgr = await self._voice_manager()
+            return await mgr.join_voice(guild_id, channel_id, self_deaf=self_deaf, self_mute=self_mute)
+        except ImportError as e:
+            return {"error": f"Voice dependencies not installed: {e}"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def leave_voice(self, guild_id: str) -> Result:
+        try:
+            mgr = await self._voice_manager()
+            return await mgr.leave_voice(guild_id)
+        except ImportError as e:
+            return {"error": f"Voice dependencies not installed: {e}"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def speak_tts(self, guild_id: str, text: str,
+                        tts_provider: str = "openai", voice: str = "alloy") -> Result:
+        try:
+            mgr = await self._voice_manager()
+            return await mgr.speak_text(guild_id, text, tts_provider=tts_provider, voice=voice)
+        except ImportError as e:
+            return {"error": f"Voice dependencies not installed: {e}"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def get_voice_status(self, guild_id: str) -> Result:
+        try:
+            mgr = await self._voice_manager()
+            return mgr.get_voice_status(guild_id)
+        except ImportError as e:
+            return {"error": f"Voice dependencies not installed: {e}"}
+        except Exception as e:
+            return {"error": str(e)}
diff --git a/app/external_comms/platforms/discord_voice_helpers.py b/craftos_integrations/integrations/discord/_discord_voice.py
similarity index 50%
rename from app/external_comms/platforms/discord_voice_helpers.py
rename to craftos_integrations/integrations/discord/_discord_voice.py
index 5852962d..5ffe1074 100644
--- a/app/external_comms/platforms/discord_voice_helpers.py
+++ b/craftos_integrations/integrations/discord/_discord_voice.py
@@ -1,34 +1,25 @@
-# -*- coding: utf-8 -*-
-"""
-Discord Voice helper functions.
-
-Voice functionality requires the discord.py library with voice support.
-Install with: pip install discord.py[voice]
-
-This module provides a VoiceManager class that handles:
-- Joining/leaving voice channels
-- Audio recording and playback
-- Integration with transcription services (OpenAI Whisper)
-- Text-to-speech with OpenAI TTS
-
-Requires:
-- discord.py[voice]: pip install discord.py[voice]
-- openai: pip install openai (for Whisper STT and TTS)
-- PyNaCl: pip install PyNaCl (for voice encryption)
-- FFmpeg: Must be installed on system
+# -*- coding: utf-8 -*-
+"""Discord voice helpers - underscore-prefixed so the autoloader skips it.
+
+Loaded lazily by discord.py only when a voice method is invoked.
+Requires extra deps (discord.py[voice], PyNaCl, FFmpeg, openai).
+
+API-key access goes through ConfigStore.extras["openai_api_key"]
+(set via configure(extras={"openai_api_key": "..."})).
 """
+from __future__ import annotations
+
 import asyncio
 import io
 import os
 import wave
 import tempfile
-from typing import Optional, Dict, Any, Callable, List
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
 
-from agent_core.core.config import get_config
+from ...config import ConfigStore
 
-# Try to import discord.py
 try:
     import discord
     from discord.ext import commands
@@ -36,7 +27,6 @@
 except ImportError:
     DISCORD_PY_AVAILABLE = False
 
-# Try to import OpenAI
 try:
     from openai import OpenAI
     OPENAI_AVAILABLE = True
@@ -45,18 +35,14 @@
 
 
 def _get_openai_audio_api_key() -> str:
-    """Get the OpenAI Audio API key from settings.json."""
-    from app.config import get_api_key
-    # Use the OpenAI API key for audio transcription
-    return get_api_key("openai")
+    return ConfigStore.extras.get("openai_api_key", "") or os.environ.get("OPENAI_API_KEY", "")
 
 
 @dataclass
 class VoiceSession:
-    """Represents an active voice session."""
     guild_id: str
     channel_id: str
-    connected_at: datetime = field(default_factory=datetime.utcnow)
+    connected_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
     is_recording: bool = False
     is_speaking: bool = False
     audio_buffer: Dict[int, List[bytes]] = field(default_factory=dict)
@@ -65,108 +51,76 @@ class VoiceSession:
 
 
 class AudioRecordingSink:
-    """
-    Custom audio sink for recording voice channel audio.
-    Collects audio from all users in the voice channel.
-    """
-
     def __init__(self, session: VoiceSession, on_audio_chunk: Optional[Callable] = None):
         self.session = session
         self.on_audio_chunk = on_audio_chunk
         self.audio_data: Dict[int, io.BytesIO] = {}
 
     def write(self, data: bytes, user_id: int):
-        """Called when audio data is received from a user."""
         if user_id not in self.audio_data:
             self.audio_data[user_id] = io.BytesIO()
-
         self.audio_data[user_id].write(data)
-
         if user_id not in self.session.audio_buffer:
             self.session.audio_buffer[user_id] = []
         self.session.audio_buffer[user_id].append(data)
-
         if self.on_audio_chunk:
             self.on_audio_chunk(user_id, data)
 
     def cleanup(self):
-        """Clean up resources."""
         for buffer in self.audio_data.values():
             buffer.close()
         self.audio_data.clear()
 
-    def get_user_audio(self, user_id: int) -> Optional[bytes]:
-        """Get recorded audio for a specific user."""
-        if user_id in self.audio_data:
-            self.audio_data[user_id].seek(0)
-            return self.audio_data[user_id].read()
-        return None
-
-    def get_all_audio(self) -> Dict[int, bytes]:
-        """Get recorded audio for all users."""
-        result = {}
-        for user_id, buffer in self.audio_data.items():
-            buffer.seek(0)
-            result[user_id] = buffer.read()
-        return result
-
 
 class DiscordVoiceManager:
-    """
-    Manages Discord voice connections for a bot.
-
-    Usage:
-        manager = DiscordVoiceManager(bot_token)
-        await manager.start()
-        await manager.join_voice(guild_id, channel_id)
-        await manager.start_recording(guild_id, transcribe_callback)
-        await manager.speak(guild_id, audio_source)
-        await manager.leave_voice(guild_id)
-    """
-
     def __init__(self, bot_token: str):
         if not DISCORD_PY_AVAILABLE:
             raise ImportError("discord.py is required for voice features. Install with: pip install discord.py[voice]")
-
         self.bot_token = bot_token
-        self.bot: Optional[commands.Bot] = None
+        self.bot: Optional[Any] = None
         self.voice_sessions: Dict[str, VoiceSession] = {}
         self._running = False
 
+    # ------------------------------------------------------------------
+    # Internal: resolve a guild (and optionally require an active voice
+    # client) before doing real work. Returns (guild, error_dict).
+    # ------------------------------------------------------------------
+    def _get_guild_or_error(self, guild_id: str, *, require_voice: bool = False):
+        if not self.bot:
+            return None, {"error": "Bot not running. Call start() first."}
+        guild = self.bot.get_guild(int(guild_id))
+        if not guild:
+            return None, {"error": f"Guild {guild_id} not found"}
+        if require_voice and not guild.voice_client:
+            return None, {"error": "Not connected to voice in this guild"}
+        return guild, None
+
     async def start(self) -> Dict[str, Any]:
-        """Start the Discord bot for voice operations."""
         try:
             intents = discord.Intents.default()
             intents.message_content = True
             intents.voice_states = True
             intents.guilds = True
-
             self.bot = commands.Bot(command_prefix="!", intents=intents)
 
             @self.bot.event
             async def on_ready():
-                print(f"Discord voice bot ready: {self.bot.user}")
                 self._running = True
 
             asyncio.create_task(self.bot.start(self.bot_token))
-
             for _ in range(30):
                 if self._running:
                     return {"ok": True, "result": {"status": "connected", "bot_user": str(self.bot.user)}}
                 await asyncio.sleep(1)
-
             return {"error": "Bot failed to connect within timeout"}
-
         except Exception as e:
             return {"error": str(e)}
 
     async def stop(self) -> Dict[str, Any]:
-        """Stop the Discord bot."""
         try:
             if self.bot:
                 for guild_id in list(self.voice_sessions.keys()):
                     await self.leave_voice(guild_id)
-
                 await self.bot.close()
                 self._running = False
                 return {"ok": True, "result": {"status": "disconnected"}}
@@ -174,334 +128,197 @@ async def stop(self) -> Dict[str, Any]:
         except Exception as e:
             return {"error": str(e)}
 
-    async def join_voice(
-        self,
-        guild_id: str,
-        channel_id: str,
-        self_deaf: bool = False,
-        self_mute: bool = False,
-    ) -> Dict[str, Any]:
-        """Join a voice channel."""
+    async def join_voice(self, guild_id: str, channel_id: str,
+                         self_deaf: bool = False, self_mute: bool = False) -> Dict[str, Any]:
         try:
-            if not self.bot or not self._running:
+            if not self._running:
                 return {"error": "Bot not running. Call start() first."}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild:
-                return {"error": f"Guild {guild_id} not found"}
-
+            guild, err = self._get_guild_or_error(guild_id)
+            if err:
+                return err
             channel = guild.get_channel(int(channel_id))
             if not channel:
                 return {"error": f"Channel {channel_id} not found"}
-
             if not isinstance(channel, discord.VoiceChannel):
                 return {"error": "Channel is not a voice channel"}
-
             if guild_id in self.voice_sessions:
                 await self.leave_voice(guild_id)
-
             await channel.connect(self_deaf=self_deaf, self_mute=self_mute)
-
-            self.voice_sessions[guild_id] = VoiceSession(
-                guild_id=guild_id,
-                channel_id=channel_id,
-            )
-
-            return {
-                "ok": True,
-                "result": {
-                    "status": "connected",
-                    "guild_id": guild_id,
-                    "channel_id": channel_id,
-                    "channel_name": channel.name,
-                }
-            }
-
+            self.voice_sessions[guild_id] = VoiceSession(guild_id=guild_id, channel_id=channel_id)
+            return {"ok": True, "result": {
+                "status": "connected", "guild_id": guild_id,
+                "channel_id": channel_id, "channel_name": channel.name,
+            }}
         except Exception as e:
             return {"error": str(e)}
 
     async def leave_voice(self, guild_id: str) -> Dict[str, Any]:
-        """Leave the voice channel in a guild."""
         try:
-            if not self.bot:
-                return {"error": "Bot not running"}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild:
-                return {"error": f"Guild {guild_id} not found"}
-
+            guild, err = self._get_guild_or_error(guild_id)
+            if err:
+                return err
             if guild.voice_client:
                 await guild.voice_client.disconnect()
-
             if guild_id in self.voice_sessions:
                 del self.voice_sessions[guild_id]
-
             return {"ok": True, "result": {"status": "disconnected", "guild_id": guild_id}}
-
         except Exception as e:
             return {"error": str(e)}
 
-    async def speak_text(
-        self,
-        guild_id: str,
-        text: str,
-        tts_provider: str = "openai",
-        voice: str = "alloy",
-    ) -> Dict[str, Any]:
-        """Speak text in the voice channel using TTS."""
+    async def speak_text(self, guild_id: str, text: str,
+                         tts_provider: str = "openai", voice: str = "alloy") -> Dict[str, Any]:
         try:
-            if not self.bot:
-                return {"error": "Bot not running"}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild or not guild.voice_client:
-                return {"error": "Not connected to voice in this guild"}
-
+            guild, err = self._get_guild_or_error(guild_id, require_voice=True)
+            if err:
+                return err
             voice_client = guild.voice_client
-
             audio_file = await self._generate_tts(text, tts_provider, voice)
             if not audio_file:
                 return {"error": "Failed to generate TTS audio"}
-
-            audio_source = discord.FFmpegPCMAudio(audio_file)
-            voice_client.play(audio_source)
-
+            voice_client.play(discord.FFmpegPCMAudio(audio_file))
             while voice_client.is_playing():
                 await asyncio.sleep(0.1)
-
             return {"ok": True, "result": {"status": "spoken", "text": text}}
-
         except Exception as e:
             return {"error": str(e)}
 
     async def play_audio(self, guild_id: str, audio_path: str) -> Dict[str, Any]:
-        """Play an audio file in the voice channel."""
         try:
-            if not self.bot:
-                return {"error": "Bot not running"}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild or not guild.voice_client:
-                return {"error": "Not connected to voice in this guild"}
-
-            voice_client = guild.voice_client
-
-            audio_source = discord.FFmpegPCMAudio(audio_path)
-            voice_client.play(audio_source)
-
+            guild, err = self._get_guild_or_error(guild_id, require_voice=True)
+            if err:
+                return err
+            guild.voice_client.play(discord.FFmpegPCMAudio(audio_path))
             return {"ok": True, "result": {"status": "playing", "audio_path": audio_path}}
-
         except Exception as e:
             return {"error": str(e)}
 
     async def stop_audio(self, guild_id: str) -> Dict[str, Any]:
-        """Stop currently playing audio."""
         try:
-            if not self.bot:
-                return {"error": "Bot not running"}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild or not guild.voice_client:
-                return {"error": "Not connected to voice in this guild"}
-
+            guild, err = self._get_guild_or_error(guild_id, require_voice=True)
+            if err:
+                return err
             guild.voice_client.stop()
             return {"ok": True, "result": {"status": "stopped"}}
-
         except Exception as e:
             return {"error": str(e)}
 
     def get_voice_status(self, guild_id: str) -> Dict[str, Any]:
-        """Get the current voice status for a guild."""
         try:
             session = self.voice_sessions.get(guild_id)
             if not session:
                 return {"ok": True, "result": {"connected": False}}
-
             guild = self.bot.get_guild(int(guild_id)) if self.bot else None
-            is_connected = guild and guild.voice_client and guild.voice_client.is_connected() if guild else False
-
-            return {
-                "ok": True,
-                "result": {
-                    "connected": is_connected,
-                    "guild_id": guild_id,
-                    "channel_id": session.channel_id,
-                    "is_recording": session.is_recording,
-                    "is_speaking": session.is_speaking,
-                    "connected_at": session.connected_at.isoformat(),
-                }
-            }
-
+            is_connected = bool(guild and guild.voice_client and guild.voice_client.is_connected())
+            return {"ok": True, "result": {
+                "connected": is_connected, "guild_id": guild_id,
+                "channel_id": session.channel_id, "is_recording": session.is_recording,
+                "is_speaking": session.is_speaking, "connected_at": session.connected_at.isoformat(),
+            }}
         except Exception as e:
             return {"error": str(e)}
 
-    async def start_listening(
-        self,
-        guild_id: str,
-        on_transcript: Optional[Callable[[int, str], None]] = None,
-        auto_transcribe: bool = True,
-        transcribe_interval: float = 3.0,
-    ) -> Dict[str, Any]:
-        """Start listening and transcribing audio in the voice channel."""
+    async def start_listening(self, guild_id: str,
+                              on_transcript: Optional[Callable[[int, str], None]] = None,
+                              auto_transcribe: bool = True,
+                              transcribe_interval: float = 3.0) -> Dict[str, Any]:
         try:
-            if not self.bot:
-                return {"error": "Bot not running"}
-
             session = self.voice_sessions.get(guild_id)
             if not session:
                 return {"error": "Not connected to voice in this guild"}
-
-            guild = self.bot.get_guild(int(guild_id))
-            if not guild or not guild.voice_client:
-                return {"error": "Not connected to voice in this guild"}
-
+            _, err = self._get_guild_or_error(guild_id, require_voice=True)
+            if err:
+                return err
             session.is_recording = True
             session.transcript_callback = on_transcript
-
             if auto_transcribe:
                 asyncio.create_task(self._auto_transcribe_loop(guild_id, transcribe_interval))
-
-            return {
-                "ok": True,
-                "result": {
-                    "status": "listening",
-                    "guild_id": guild_id,
-                    "auto_transcribe": auto_transcribe,
-                }
-            }
-
+            return {"ok": True, "result": {"status": "listening", "guild_id": guild_id, "auto_transcribe": auto_transcribe}}
         except Exception as e:
             return {"error": str(e)}
 
     async def stop_listening(self, guild_id: str) -> Dict[str, Any]:
-        """Stop listening in the voice channel."""
         try:
             session = self.voice_sessions.get(guild_id)
             if not session:
                 return {"error": "No active session for this guild"}
-
             session.is_recording = False
-
             final_transcripts = dict(session.last_transcripts)
             session.audio_buffer.clear()
-
-            return {
-                "ok": True,
-                "result": {
-                    "status": "stopped",
-                    "transcripts": final_transcripts,
-                }
-            }
-
+            return {"ok": True, "result": {"status": "stopped", "transcripts": final_transcripts}}
         except Exception as e:
             return {"error": str(e)}
 
     async def _auto_transcribe_loop(self, guild_id: str, interval: float):
-        """Background task to automatically transcribe audio at intervals."""
         while True:
             session = self.voice_sessions.get(guild_id)
             if not session or not session.is_recording:
                 break
-
             for user_id, chunks in list(session.audio_buffer.items()):
                 if chunks and len(chunks) > 10:
-                    audio_data = b''.join(chunks)
+                    audio_data = b"".join(chunks)
                     session.audio_buffer[user_id] = []
-
                     transcript = await self._transcribe_audio(audio_data)
                     if transcript:
                         session.last_transcripts[user_id] = transcript
                         if session.transcript_callback:
                             try:
                                 session.transcript_callback(user_id, transcript)
-                            except Exception as e:
-                                print(f"Transcript callback error: {e}")
-
+                            except Exception:
+                                pass
             await asyncio.sleep(interval)
 
     async def _transcribe_audio(self, audio_data: bytes) -> Optional[str]:
-        """Transcribe audio data using OpenAI Whisper."""
         api_key = _get_openai_audio_api_key()
         if not OPENAI_AVAILABLE or not api_key:
-            print("OpenAI not available for transcription. Set OPENAI_AUDIO_API_KEY.")
             return None
-
         try:
             wav_path = self._pcm_to_wav(audio_data)
             if not wav_path:
                 return None
-
             client = OpenAI(api_key=api_key)
-
             with open(wav_path, "rb") as audio_file:
                 transcript = client.audio.transcriptions.create(
-                    model="whisper-1",
-                    file=audio_file,
-                    response_format="text"
+                    model="whisper-1", file=audio_file, response_format="text",
                 )
-
             os.unlink(wav_path)
-
             return transcript.strip() if transcript else None
-
-        except Exception as e:
-            print(f"Transcription error: {e}")
+        except Exception:
             return None
 
     def _pcm_to_wav(self, pcm_data: bytes, sample_rate: int = 48000, channels: int = 2) -> Optional[str]:
-        """Convert raw PCM audio data to WAV file."""
         try:
-            with tempfile.NamedTemporaryFile(delete=False, suffix='.wav') as f:
-                with wave.open(f.name, 'wb') as wav_file:
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".wav") as f:
+                with wave.open(f.name, "wb") as wav_file:
                     wav_file.setnchannels(channels)
                     wav_file.setsampwidth(2)
                     wav_file.setframerate(sample_rate)
                     wav_file.writeframes(pcm_data)
                 return f.name
-        except Exception as e:
-            print(f"PCM to WAV conversion error: {e}")
+        except Exception:
             return None
 
     async def _generate_tts(self, text: str, provider: str = "openai", voice: str = "alloy") -> Optional[str]:
-        """Generate TTS audio file from text."""
         try:
             api_key = _get_openai_audio_api_key()
             if provider == "openai" and OPENAI_AVAILABLE and api_key:
                 client = OpenAI(api_key=api_key)
-
-                response = client.audio.speech.create(
-                    model="tts-1",
-                    voice=voice,
-                    input=text,
-                )
-
-                with tempfile.NamedTemporaryFile(delete=False, suffix='.mp3') as f:
+                response = client.audio.speech.create(model="tts-1", voice=voice, input=text)
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".mp3") as f:
                     response.stream_to_file(f.name)
                     return f.name
-
             elif provider == "gtts" or not OPENAI_AVAILABLE:
                 from gtts import gTTS
-                tts = gTTS(text=text, lang='en')
-                with tempfile.NamedTemporaryFile(delete=False, suffix='.mp3') as f:
+                tts = gTTS(text=text, lang="en")
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".mp3") as f:
                     tts.save(f.name)
                     return f.name
-
-            return None
-
-        except ImportError:
-            print("TTS library not available. Install gtts: pip install gtts")
             return None
-        except Exception as e:
-            print(f"TTS generation error: {e}")
+        except Exception:
             return None
 
-    async def transcribe_and_respond(
-        self,
-        guild_id: str,
-        response_generator: Callable[[str], str],
-        voice: str = "alloy",
-    ) -> Dict[str, Any]:
-        """Listen for speech, transcribe it, generate a response, and speak it back."""
+    async def transcribe_and_respond(self, guild_id: str,
+                                     response_generator: Callable[[str], str],
+                                     voice: str = "alloy") -> Dict[str, Any]:
         try:
             session = self.voice_sessions.get(guild_id)
             if not session:
@@ -510,65 +327,14 @@ async def transcribe_and_respond(
             async def on_transcript(user_id: int, transcript: str):
                 if not transcript or len(transcript.strip()) < 2:
                     return
-
-                print(f"[Voice] User {user_id} said: {transcript}")
-
                 response_text = response_generator(transcript)
                 if response_text:
-                    print(f"[Voice] Responding: {response_text}")
                     await self.speak_text(guild_id, response_text, tts_provider="openai", voice=voice)
 
-            result = await self.start_listening(
+            return await self.start_listening(
                 guild_id=guild_id,
                 on_transcript=lambda uid, txt: asyncio.create_task(on_transcript(uid, txt)),
                 auto_transcribe=True,
             )
-
-            return result
-
         except Exception as e:
             return {"error": str(e)}
-
-
-def get_voice_regions() -> Dict[str, Any]:
-    """Get available Discord voice regions."""
-    import requests
-
-    url = "https://discord.com/api/v10/voice/regions"
-
-    try:
-        response = requests.get(url, timeout=15)
-
-        if response.status_code == 200:
-            return {"ok": True, "result": {"regions": response.json()}}
-        else:
-            return {"error": f"API error: {response.status_code}"}
-    except Exception as e:
-        return {"error": str(e)}
-
-
-def get_guild_voice_states(bot_token: str, guild_id: str) -> Dict[str, Any]:
-    """Get voice states for a guild (who's in voice channels)."""
-    import requests
-
-    url = f"https://discord.com/api/v10/guilds/{guild_id}"
-    headers = {
-        "Authorization": f"Bot {bot_token}",
-        "Content-Type": "application/json",
-    }
-
-    try:
-        response = requests.get(url, headers=headers, timeout=15)
-
-        if response.status_code == 200:
-            data = response.json()
-            return {
-                "ok": True,
-                "result": {
-                    "voice_states": data.get("voice_states", []),
-                }
-            }
-        else:
-            return {"error": f"API error: {response.status_code}", "details": response.text}
-    except Exception as e:
-        return {"error": str(e)}
diff --git a/craftos_integrations/integrations/github/INTEGRATION.md b/craftos_integrations/integrations/github/INTEGRATION.md
new file mode 100644
index 00000000..ca641993
--- /dev/null
+++ b/craftos_integrations/integrations/github/INTEGRATION.md
@@ -0,0 +1,11 @@
+# GitHub — Integration Reference
+
+REST + notification-polling integration via a personal access token. Issues, PRs, comments, labels, and notification dispatch.
+
+## Essentials
+
+- **Issue / PR identifier is `owner/repo#number`** (e.g. `acme/web#42`). Numeric IDs on their own are ambiguous — always include `owner/repo`. Pull from `list_github_issues` / notifications; don't construct.
+- **`watch_tag` and `watch_repos` config silently drop traffic.** If `watch_tag` is set, the poller skips any notification whose comment doesn't contain the tag. If `watch_repos` is non-empty, notifications from any repo not in the list are dropped before the router sees them. If incoming events stop, check these first.
+- **Session-level facts:** `cred.username` is set at login. Don't ask the user for their GitHub handle — read the credential.
+- **Token scope failures don't recover by retry.** A `403` (or `404` on a known repo) usually means the PAT lacks the required scope (`repo`, `workflow`, `notifications`). Direct the user to regenerate the token with broader scopes; retrying the same call is futile.
+- **Notification IDs are opaque** strings from the GitHub API — pass them through, never construct.
diff --git a/craftos_integrations/integrations/github/__init__.py b/craftos_integrations/integrations/github/__init__.py
new file mode 100644
index 00000000..5934cd91
--- /dev/null
+++ b/craftos_integrations/integrations/github/__init__.py
@@ -0,0 +1,572 @@
+# -*- coding: utf-8 -*-
+"""GitHub integration — handler + client + credential.
+
+This is the canonical example of an integration package:
+  - one credential dataclass
+  - one IntegrationSpec (referenced by both handler and client = composition)
+  - one IntegrationHandler (auth: login/logout/status)
+  - one BasePlatformClient (runtime: notification polling, REST API)
+
+To add another integration, copy this folder and adapt.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    save_config,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+GITHUB_API = "https://api.github.com"
+POLL_INTERVAL = 15
+RETRY_DELAY = 30
+
+
+@dataclass
+class GitHubCredential:
+    access_token: str = ""
+    username: str = ""
+
+
+@dataclass
+class GitHubConfig:
+    """Runtime knobs separate from the credential - loaded fresh from
+    ``github_config.json`` whenever the client reads them."""
+    watch_tag: str = ""
+    watch_repos: List[str] = field(default_factory=list)
+
+
+GITHUB = IntegrationSpec(
+    name="github",
+    cred_class=GitHubCredential,
+    cred_file="github.json",
+    platform_id="github",
+)
+
+
+def _github_config_file() -> str:
+    """``github.json`` → ``github_config.json`` - must match the convention
+    in ``service._config_filename``."""
+    stem = GITHUB.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler - auth flows
+# -----------------------------------------------------------------
+
+@register_handler(GITHUB.name)
+class GitHubHandler(IntegrationHandler):
+    spec = GITHUB
+    display_name = "GitHub"
+    description = "Repositories, issues, and pull requests"
+    auth_type = "token"
+    icon = "github"
+    connect_help = [
+        "Open GitHub: github.com/settings/tokens",
+        "Click 'Generate new token' → 'Generate new token (classic)'",
+        "Set scopes: at minimum 'repo' (issues + PRs) - add 'workflow' if needed",
+        "Copy the ghp_... token before leaving the page (shown once)",
+    ]
+    fields = [
+        {"key": "access_token", "label": "Personal Access Token", "placeholder": "ghp_...", "password": True},
+    ]
+    config_class = GitHubConfig
+    config_fields = [
+        {"key": "watch_tag", "label": "Watch tag", "type": "text",
+         "placeholder": "@craftbot",
+         "help": "Trigger keyword in PR/issue comments. Leave empty to react to all events."},
+        {"key": "watch_repos", "label": "Watched repos", "type": "list",
+         "placeholder": "owner/repo",
+         "help": "Comma-separated. Leave empty to watch every repo the token has access to."},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, (
+                "Usage: /github login <personal_access_token>\n"
+                "Generate one at: https://github.com/settings/tokens"
+            )
+        token = args[0].strip()
+
+        result = http_request(
+            "GET", "https://api.github.com/user",
+            headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
+            expected=(200,),
+        )
+        if "error" in result:
+            return False, f"GitHub auth failed: {result['error']}"
+        data = result["result"]
+
+        save_credential(self.spec.cred_file, GitHubCredential(
+            access_token=token,
+            username=data.get("login", ""),
+        ))
+        return True, f"GitHub connected as @{data.get('login')} ({data.get('name', '')})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No GitHub credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed GitHub credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "GitHub: Not connected"
+        cred = load_credential(self.spec.cred_file, GitHubCredential)
+        if not cred:
+            return True, "GitHub: Not connected"
+        username = cred.username or "unknown"
+        cfg = load_config(_github_config_file(), GitHubConfig) or GitHubConfig()
+        tag_info = f" [tag: {cfg.watch_tag}]" if cfg.watch_tag else ""
+        repos_info = f" [repos: {', '.join(cfg.watch_repos)}]" if cfg.watch_repos else ""
+        return True, f"GitHub: Connected\n  - @{username}{tag_info}{repos_info}"
+
+
+# -----------------------------------------------------------------
+# Client - runtime: REST API + notification polling
+# -----------------------------------------------------------------
+
+@register_client
+class GitHubClient(BasePlatformClient):
+    spec = GITHUB
+    PLATFORM_ID = GITHUB.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[GitHubCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._last_modified: Optional[str] = None
+        self._seen_ids: set = set()
+        self._catchup_done: bool = False
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> GitHubCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, GitHubCredential)
+        if self._cred is None:
+            raise RuntimeError("No GitHub credentials. Use /github login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        return {
+            "Authorization": f"Bearer {cred.access_token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        try:
+            repo_part, number = recipient.rsplit("#", 1)
+            return await self.create_comment(repo_part.strip(), int(number), text)
+        except (ValueError, IndexError):
+            return {"error": f"Invalid recipient format. Use 'owner/repo#number', got: {recipient}"}
+
+    # ----- Watch tag / repos (read from github_config.json) -----
+
+    def _config_file(self) -> str:
+        # Convention: <cred-stem>_config.json (matches service._config_filename)
+        stem = self.spec.cred_file
+        return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+    def _config(self) -> GitHubConfig:
+        """Load the runtime config fresh each time. Cheap (small JSON read)
+        and avoids stale-cache bugs when the user updates from the UI."""
+        return load_config(self._config_file(), GitHubConfig) or GitHubConfig()
+
+    def get_watch_tag(self) -> str:
+        return self._config().watch_tag
+
+    def set_watch_tag(self, tag: str) -> None:
+        cfg = self._config()
+        cfg.watch_tag = tag.strip()
+        save_config(self._config_file(), cfg)
+        logger.info(f"[GITHUB] Watch tag set to: {cfg.watch_tag or '(disabled)'}")
+
+    def get_watch_repos(self) -> List[str]:
+        return list(self._config().watch_repos)
+
+    def set_watch_repos(self, repos: List[str]) -> None:
+        cfg = self._config()
+        cfg.watch_repos = [r.strip() for r in repos if r.strip()]
+        save_config(self._config_file(), cfg)
+        logger.info(f"[GITHUB] Watch repos set to: {cfg.watch_repos or '(all)'}")
+
+    # ----- Listening -----
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+
+        self._message_callback = callback
+        self._load()
+
+        me = await self.get_authenticated_user()
+        if "error" in me:
+            raise RuntimeError(f"Invalid GitHub token: {me.get('error')}")
+
+        username = me.get("result", {}).get("login", "unknown")
+        logger.info(f"[GITHUB] Authenticated as: {username}")
+
+        cred = self._load()
+        if cred.username != username:
+            cred.username = username
+            save_credential(self.spec.cred_file, cred)
+            self._cred = cred
+
+        self._last_modified = datetime.now(timezone.utc).strftime("%a, %d %b %Y %H:%M:%S GMT")
+        self._catchup_done = True
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+        cfg = self._config()
+        tag_info = cfg.watch_tag or "(disabled - all events)"
+        repos_info = ", ".join(cfg.watch_repos) if cfg.watch_repos else "(all repos)"
+        logger.info(f"[GITHUB] Poller started - tag: {tag_info} | repos: {repos_info}")
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+        logger.info("[GITHUB] Poller stopped")
+
+    async def _poll_loop(self) -> None:
+        while self._listening:
+            try:
+                await self._check_notifications()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[GITHUB] Poll error: {e}")
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    def _check_notifications_sync(self) -> Optional[Dict[str, Any]]:
+        """Sync notification poll - returns ``{notifications, last_modified}`` or
+        ``None`` if 304/401/other status. Wrapped in ``asyncio.to_thread`` from
+        ``_check_notifications`` to avoid anyio's task-tracking issues on
+        Python 3.14 conda-forge.
+        """
+        headers = self._headers()
+        if self._last_modified:
+            headers["If-Modified-Since"] = self._last_modified
+        try:
+            resp = httpx.get(
+                f"{GITHUB_API}/notifications",
+                headers=headers,
+                params={"all": "false", "participating": "true"},
+                timeout=30.0,
+            )
+        except Exception as e:
+            logger.warning(f"[GITHUB] Notifications request failed: {e}")
+            return None
+        if resp.status_code == 304:
+            return None
+        if resp.status_code == 401:
+            logger.warning("[GITHUB] Authentication expired (401)")
+            return None
+        if resp.status_code != 200:
+            logger.warning(f"[GITHUB] Notifications API error: {resp.status_code}")
+            return None
+        return {
+            "notifications": resp.json(),
+            "last_modified": resp.headers.get("Last-Modified"),
+        }
+
+    async def _check_notifications(self) -> None:
+        cfg = self._config()
+        result = await asyncio.to_thread(self._check_notifications_sync)
+        if result is None:
+            return
+
+        if result["last_modified"]:
+            self._last_modified = result["last_modified"]
+
+        for notif in result["notifications"]:
+            notif_id = notif.get("id", "")
+            if notif_id in self._seen_ids:
+                continue
+            self._seen_ids.add(notif_id)
+
+            repo_full = notif.get("repository", {}).get("full_name", "")
+            if cfg.watch_repos and repo_full not in cfg.watch_repos:
+                continue
+
+            await self._dispatch_notification(notif)
+
+        if len(self._seen_ids) > 500:
+            self._seen_ids = set(list(self._seen_ids)[-200:])
+
+    def _fetch_comment_sync(self, url: str) -> tuple[str, str]:
+        """Sync per-comment fetch - returns ``(body, author)`` or ``("", "")``."""
+        try:
+            cr = httpx.get(url, headers=self._headers(), timeout=15.0)
+            if cr.status_code != 200:
+                return "", ""
+            data = cr.json()
+            return data.get("body", ""), data.get("user", {}).get("login", "")
+        except Exception:
+            return "", ""
+
+    async def _dispatch_notification(self, notif: Dict[str, Any]) -> None:
+        if not self._message_callback:
+            return
+
+        cfg = self._config()
+        reason = notif.get("reason", "")
+        subject = notif.get("subject", {})
+        subject_type = subject.get("type", "")
+        subject_title = subject.get("title", "")
+        repo = notif.get("repository", {})
+        repo_full = repo.get("full_name", "")
+
+        latest_comment_url = subject.get("latest_comment_url", "")
+        comment_body = ""
+        comment_author = ""
+        if latest_comment_url:
+            comment_body, comment_author = await asyncio.to_thread(
+                self._fetch_comment_sync, latest_comment_url,
+            )
+
+        watch_tag = cfg.watch_tag
+        if watch_tag:
+            if not comment_body or watch_tag.lower() not in comment_body.lower():
+                return
+
+            tag_lower = watch_tag.lower()
+            idx = comment_body.lower().find(tag_lower)
+            instruction = comment_body[idx + len(watch_tag):].strip() if idx >= 0 else comment_body
+
+            text_parts = [
+                f"[{repo_full}] {subject_type}: {subject_title}",
+                f"Comment by @{comment_author}: {instruction}",
+            ]
+
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=comment_author,
+                sender_name=comment_author,
+                text="\n".join(text_parts),
+                channel_id=repo_full,
+                channel_name=repo_full,
+                message_id=notif.get("id", ""),
+                timestamp=datetime.now(timezone.utc),
+                raw={
+                    "notification": notif,
+                    "trigger": "comment_tag",
+                    "tag": watch_tag,
+                    "instruction": instruction,
+                    "comment_body": comment_body,
+                    "comment_author": comment_author,
+                },
+            ))
+            logger.info(f"[GITHUB] Tag '{watch_tag}' matched in {repo_full} by @{comment_author}")
+            return
+
+        text_parts = [
+            f"[{repo_full}] {subject_type}: {subject_title}",
+            f"Reason: {reason}",
+        ]
+        if comment_body:
+            text_parts.append(f"Comment by @{comment_author}: {comment_body[:300]}")
+
+        await self._message_callback(PlatformMessage(
+            platform=self.spec.platform_id,
+            sender_id=comment_author or "",
+            sender_name=comment_author or reason,
+            text="\n".join(text_parts),
+            channel_id=repo_full,
+            channel_name=repo_full,
+            message_id=notif.get("id", ""),
+            timestamp=datetime.now(timezone.utc),
+            raw=notif,
+        ))
+
+    # ----- REST API methods -----
+
+    async def get_authenticated_user(self) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/user",
+            headers=self._headers(),
+            expected=(200,),
+            transform=lambda d: {"login": d.get("login"), "name": d.get("name"), "id": d.get("id")},
+        )
+
+    async def list_repos(self, per_page: int = 30, sort: str = "updated") -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/user/repos",
+            headers=self._headers(),
+            params={"per_page": per_page, "sort": sort},
+            expected=(200,),
+            transform=lambda d: {"repos": [
+                {"full_name": r.get("full_name"), "name": r.get("name"), "private": r.get("private"), "description": r.get("description", "")}
+                for r in d
+            ]},
+        )
+
+    async def get_repo(self, owner_repo: str) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/repos/{owner_repo}",
+            headers=self._headers(),
+            expected=(200,),
+        )
+
+    async def list_issues(self, owner_repo: str, state: str = "open", per_page: int = 30) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/repos/{owner_repo}/issues",
+            headers=self._headers(),
+            params={"state": state, "per_page": per_page},
+            expected=(200,),
+            transform=lambda d: {"issues": [
+                {
+                    "number": i.get("number"),
+                    "title": i.get("title"),
+                    "state": i.get("state"),
+                    "user": i.get("user", {}).get("login", ""),
+                    "labels": [l.get("name") for l in i.get("labels", [])],
+                    "assignees": [a.get("login") for a in i.get("assignees", [])],
+                    "created_at": i.get("created_at"),
+                    "updated_at": i.get("updated_at"),
+                    "is_pr": "pull_request" in i,
+                }
+                for i in d
+            ]},
+        )
+
+    async def get_issue(self, owner_repo: str, number: int) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/repos/{owner_repo}/issues/{number}",
+            headers=self._headers(),
+            expected=(200,),
+        )
+
+    async def create_issue(self, owner_repo: str, title: str, body: str = "", labels: Optional[List[str]] = None, assignees: Optional[List[str]] = None) -> Result:
+        payload: Dict[str, Any] = {"title": title}
+        if body:
+            payload["body"] = body
+        if labels:
+            payload["labels"] = labels
+        if assignees:
+            payload["assignees"] = assignees
+        return await arequest(
+            "POST", f"{GITHUB_API}/repos/{owner_repo}/issues",
+            headers=self._headers(),
+            json=payload,
+            transform=lambda d: {"number": d.get("number"), "html_url": d.get("html_url"), "title": d.get("title")},
+        )
+
+    async def create_comment(self, owner_repo: str, number: int, body: str) -> Result:
+        return await arequest(
+            "POST", f"{GITHUB_API}/repos/{owner_repo}/issues/{number}/comments",
+            headers=self._headers(),
+            json={"body": body},
+            transform=lambda d: {"id": d.get("id"), "html_url": d.get("html_url")},
+        )
+
+    async def list_pull_requests(self, owner_repo: str, state: str = "open", per_page: int = 30) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/repos/{owner_repo}/pulls",
+            headers=self._headers(),
+            params={"state": state, "per_page": per_page},
+            expected=(200,),
+            transform=lambda d: {"pull_requests": [
+                {
+                    "number": p.get("number"),
+                    "title": p.get("title"),
+                    "state": p.get("state"),
+                    "user": p.get("user", {}).get("login", ""),
+                    "head": p.get("head", {}).get("ref", ""),
+                    "base": p.get("base", {}).get("ref", ""),
+                    "draft": p.get("draft", False),
+                    "created_at": p.get("created_at"),
+                }
+                for p in d
+            ]},
+        )
+
+    async def search_issues(self, query: str, per_page: int = 20) -> Result:
+        return await arequest(
+            "GET", f"{GITHUB_API}/search/issues",
+            headers=self._headers(),
+            params={"q": query, "per_page": per_page},
+            timeout=30.0,
+            expected=(200,),
+            transform=lambda d: {
+                "total_count": d.get("total_count", 0),
+                "items": [
+                    {
+                        "number": i.get("number"),
+                        "title": i.get("title"),
+                        "state": i.get("state"),
+                        "repo": i.get("repository_url", "").split("/repos/")[-1] if i.get("repository_url") else "",
+                        "user": i.get("user", {}).get("login", ""),
+                        "html_url": i.get("html_url"),
+                    }
+                    for i in d.get("items", [])
+                ],
+            },
+        )
+
+    async def add_labels(self, owner_repo: str, number: int, labels: List[str]) -> Result:
+        return await arequest(
+            "POST", f"{GITHUB_API}/repos/{owner_repo}/issues/{number}/labels",
+            headers=self._headers(),
+            json={"labels": labels},
+            expected=(200,),
+            transform=lambda _d: {"labels_added": labels},
+        )
+
+    async def close_issue(self, owner_repo: str, number: int) -> Result:
+        return await arequest(
+            "PATCH", f"{GITHUB_API}/repos/{owner_repo}/issues/{number}",
+            headers=self._headers(),
+            json={"state": "closed"},
+            expected=(200,),
+            transform=lambda _d: {"closed": True, "number": number},
+        )
diff --git a/craftos_integrations/integrations/gmail/INTEGRATION.md b/craftos_integrations/integrations/gmail/INTEGRATION.md
new file mode 100644
index 00000000..691e8522
--- /dev/null
+++ b/craftos_integrations/integrations/gmail/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Gmail — Integration Reference
+
+Send and read mail from the user's connected Google account. Part of the Google Workspace bundle (shares OAuth credentials with `google_calendar`, `google_drive`, `google_docs`).
+
+## Essentials
+
+- **The integration knows the user's own email address** (`cred.email`). NEVER ask the user for it. Read the connected credential or call `check_integration_status("google")` if you need it.
+- **`From` is always the connected account.** You cannot spoof sender on send.
+- **Self-emails are auto-filtered on incoming events** — the agent's own outgoing mail doesn't loop back as new mail.
+- **Identity format:** plain email-address strings (e.g. `alice@example.com`). Multiple recipients: depends on action; read the schema.
+- **Message IDs are Gmail-opaque strings.** Don't construct them; always pull from `list_gmail` / search results.
+- **`process_incoming=False` config:** if set, incoming mail is silently dropped (the agent never sees new emails). Sending and reading still work. If a user expected push-style notifications and isn't getting any, check this flag first.
+- **`historyId` 404 is self-healing.** The internal polling sometimes returns 404 when the historyId expires — the client transparently re-fetches. Don't surface or retry.
diff --git a/craftos_integrations/integrations/gmail/__init__.py b/craftos_integrations/integrations/gmail/__init__.py
new file mode 100644
index 00000000..9d0744d8
--- /dev/null
+++ b/craftos_integrations/integrations/gmail/__init__.py
@@ -0,0 +1,373 @@
+# -*- coding: utf-8 -*-
+"""Gmail - granular Google integration.
+
+A user can connect just Gmail (without granting Calendar/Drive/YouTube
+scopes) by clicking Connect on the Gmail card. The credential is saved
+to ``gmail.json``. The "Google Workspace" meta-integration also writes
+to this file when it cascades, so they stay interchangeable.
+
+Structure mirrors any single-purpose integration in this package — see
+``github/`` for the canonical shape. The Google-specific pieces
+(``GoogleCredential``, ``OAuthFlow`` factory, token refresh) live in
+``../_google_common.py`` and are shared with the other per-service
+integrations (calendar / drive / docs / youtube).
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import mimetypes
+import os
+from dataclasses import dataclass
+from datetime import timezone
+from email import encoders
+from email.mime.base import MIMEBase
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    load_config,
+    register_client,
+    register_handler,
+)
+from ...helpers import Result, arequest, request as http_request
+from ...logger import get_logger
+from .._google_common import (
+    GMAIL_SCOPES,
+    GoogleApiClientMixin,
+    GoogleCredential,
+    make_google_oauth,
+    run_google_login,
+    run_google_logout,
+    run_google_status,
+)
+
+logger = get_logger(__name__)
+
+GMAIL_API_BASE = "https://gmail.googleapis.com/gmail/v1"
+POLL_INTERVAL = 5
+RETRY_DELAY = 10
+
+
+GMAIL = IntegrationSpec(
+    name="gmail",
+    cred_class=GoogleCredential,
+    cred_file="gmail.json",
+    platform_id="gmail",
+)
+
+
+@dataclass
+class GmailConfig:
+    """Runtime knobs persisted to ``gmail_config.json``."""
+    # When True (default), every new INBOX message is forwarded to the
+    # agent as a PlatformMessage. When False, the listener still polls
+    # Gmail history (so send/read REST methods stay live) but does not
+    # dispatch incoming emails to the agent - Gmail becomes effectively
+    # send-only.
+    process_incoming: bool = True
+
+
+def _gmail_config_file() -> str:
+    """``gmail.json`` → ``gmail_config.json``."""
+    stem = GMAIL.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler - auth flow only
+# -----------------------------------------------------------------
+
+@register_handler(GMAIL.name)
+class GmailHandler(IntegrationHandler):
+    spec = GMAIL
+    display_name = "Gmail"
+    description = "Email - read, search, and send"
+    auth_type = "oauth"
+    icon = "gmail"
+    fields: List = []
+
+    config_class = GmailConfig
+    config_fields = [
+        {"key": "process_incoming", "label": "Auto-process incoming emails", "type": "checkbox",
+         "help": "When on, every new INBOX message is forwarded to the agent. "
+                 "Turn off to keep Gmail send-only - the agent ignores incoming mail."},
+    ]
+
+    oauth = make_google_oauth(GMAIL_SCOPES)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_login(self.spec, self.oauth, "Gmail")
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_logout(self.spec, "Gmail")
+
+    async def status(self) -> Tuple[bool, str]:
+        return await run_google_status(self.spec, "Gmail")
+
+
+# -----------------------------------------------------------------
+# Client - Gmail listener + REST methods
+# -----------------------------------------------------------------
+
+@register_client
+class GmailClient(GoogleApiClientMixin, BasePlatformClient):
+    # Mixin first so its concrete ``has_credentials`` / ``_load`` / token
+    # methods satisfy ``BasePlatformClient``'s abstract slots. See
+    # ``_google_common.py`` for the rationale.
+    spec = GMAIL
+    PLATFORM_ID = GMAIL.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[GoogleCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._history_id: Optional[str] = None
+        self._seen_message_ids: set = set()
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return self.send_email(to=recipient, subject=kwargs.get("subject", ""), body=text)
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        self._load()
+
+        try:
+            profile = await self._async_get_profile()
+            self._history_id = profile.get("historyId")
+            logger.info(f"[GMAIL] profile: {profile.get('emailAddress')}, historyId: {self._history_id}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to connect to Gmail: {e}")
+
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    # ----- Listener internals -----
+
+    async def _async_get_profile(self) -> Dict[str, Any]:
+        result = await arequest("GET", f"{GMAIL_API_BASE}/users/me/profile",
+                                headers=self._auth_header(), expected=(200,))
+        if "error" in result:
+            raise RuntimeError(f"Gmail profile {result['error']}")
+        return result["result"]
+
+    async def _poll_loop(self) -> None:
+        while self._listening:
+            try:
+                await self._check_history()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[GMAIL] Poll error: {e}")
+                if "404" in str(e) or "historyId" in str(e).lower():
+                    try:
+                        profile = await self._async_get_profile()
+                        self._history_id = profile.get("historyId")
+                    except Exception:
+                        pass
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    async def _check_history(self) -> None:
+        if not self._history_id:
+            return
+        result = await arequest(
+            "GET", f"{GMAIL_API_BASE}/users/me/history",
+            headers=self._auth_header(),
+            params={"startHistoryId": self._history_id, "historyTypes": "messageAdded", "labelId": "INBOX"},
+            expected=(200,),
+        )
+        if "error" in result:
+            if "404" in result["error"]:
+                raise RuntimeError("historyId expired (404)")
+            logger.warning(f"[GMAIL] history.list {result['error']}")
+            return
+
+        data = result["result"] or {}
+        new_history_id = data.get("historyId")
+        if new_history_id:
+            self._history_id = new_history_id
+
+        new_msg_ids = []
+        for record in data.get("history", []):
+            for added in record.get("messagesAdded", []):
+                msg = added.get("message", {})
+                msg_id = msg.get("id", "")
+                if msg_id and "INBOX" in msg.get("labelIds", []) and msg_id not in self._seen_message_ids:
+                    new_msg_ids.append(msg_id)
+                    self._seen_message_ids.add(msg_id)
+
+        if len(self._seen_message_ids) > 500:
+            self._seen_message_ids = set(list(self._seen_message_ids)[-200:])
+
+        for msg_id in new_msg_ids:
+            try:
+                await self._fetch_and_dispatch(msg_id)
+            except Exception as e:
+                logger.debug(f"[GMAIL] Error processing message {msg_id}: {e}")
+
+    async def _fetch_and_dispatch(self, msg_id: str) -> None:
+        cfg = load_config(_gmail_config_file(), GmailConfig) or GmailConfig()
+        if not cfg.process_incoming:
+            return
+
+        result = await arequest(
+            "GET", f"{GMAIL_API_BASE}/users/me/messages/{msg_id}",
+            headers=self._auth_header(),
+            params=[("format", "metadata"), ("metadataHeaders", "From"),
+                    ("metadataHeaders", "Subject"), ("metadataHeaders", "Date")],
+            expected=(200,),
+        )
+        if "error" in result:
+            return
+
+        msg = result["result"]
+        headers = {h["name"]: h["value"] for h in msg.get("payload", {}).get("headers", [])}
+        from_header = headers.get("From", "")
+        subject = headers.get("Subject", "(no subject)")
+        snippet = msg.get("snippet", "")
+
+        sender_name = from_header
+        sender_email = from_header
+        if "<" in from_header and ">" in from_header:
+            parts = from_header.rsplit("<", 1)
+            sender_name = parts[0].strip().strip('"')
+            sender_email = parts[1].rstrip(">").strip()
+
+        cred = self._load()
+        if sender_email.lower() == (cred.email or "").lower():
+            return
+
+        timestamp = None
+        try:
+            from email.utils import parsedate_to_datetime
+            timestamp = parsedate_to_datetime(headers.get("Date", ""))
+            if timestamp.tzinfo is None:
+                timestamp = timestamp.replace(tzinfo=timezone.utc)
+        except Exception:
+            pass
+
+        text = f"Subject: {subject}\n{snippet}" if snippet else f"Subject: {subject}"
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=sender_email,
+                sender_name=sender_name or sender_email,
+                text=text,
+                channel_id=msg.get("threadId", ""),
+                message_id=msg_id,
+                timestamp=timestamp,
+                raw=msg,
+            ))
+
+    # ----- REST methods -----
+
+    @staticmethod
+    def _encode_email(to_email: str, from_email: str, subject: str, body: str,
+                      attachments: Optional[List[str]] = None) -> str:
+        msg = MIMEMultipart()
+        msg["to"] = to_email
+        msg["from"] = from_email
+        msg["subject"] = subject
+        msg.attach(MIMEText(body, "plain"))
+
+        if attachments:
+            for file_path in attachments:
+                if not os.path.isfile(file_path):
+                    continue
+                mime_type, _ = mimetypes.guess_type(file_path)
+                if mime_type is None:
+                    mime_type = "application/octet-stream"
+                maintype, subtype = mime_type.split("/", 1)
+                with open(file_path, "rb") as f:
+                    part = MIMEBase(maintype, subtype)
+                    part.set_payload(f.read())
+                    encoders.encode_base64(part)
+                    part.add_header("Content-Disposition", f'attachment; filename="{os.path.basename(file_path)}"')
+                    msg.attach(part)
+
+        return base64.urlsafe_b64encode(msg.as_bytes()).decode()
+
+    def send_email(self, to: str, subject: str, body: str,
+                   from_email: Optional[str] = None,
+                   attachments: Optional[List[str]] = None) -> Result:
+        cred = self._load()
+        sender = from_email or cred.email
+        raw = self._encode_email(to, sender, subject, body, attachments)
+        return http_request(
+            "POST", f"{GMAIL_API_BASE}/users/me/messages/send",
+            headers=self._headers(), json={"raw": raw}, expected=(200,),
+        )
+
+    def list_emails(self, n: int = 5, unread_only: bool = True) -> Result:
+        params: Dict[str, Any] = {"maxResults": n, "labelIds": ["INBOX"]}
+        if unread_only:
+            params["q"] = "is:unread"
+        return http_request(
+            "GET", f"{GMAIL_API_BASE}/users/me/messages",
+            headers=self._auth_header(), params=params, expected=(200,),
+            transform=lambda d: d.get("messages", []),
+        )
+
+    def get_email(self, message_id: str, full_body: bool = False) -> Result:
+        format_type = "full" if full_body else "metadata"
+
+        def _shape(msg):
+            email_info: Dict[str, Any] = {
+                "id": msg.get("id"), "snippet": msg.get("snippet", ""),
+                "headers": {h["name"]: h["value"] for h in msg.get("payload", {}).get("headers", [])},
+            }
+            if full_body and "parts" in msg.get("payload", {}):
+                for part in msg["payload"]["parts"]:
+                    if part.get("mimeType") == "text/plain" and "data" in part.get("body", {}):
+                        email_info["body"] = base64.urlsafe_b64decode(
+                            part["body"]["data"].encode("ASCII")
+                        ).decode("utf-8")
+                        break
+            return email_info
+
+        return http_request(
+            "GET", f"{GMAIL_API_BASE}/users/me/messages/{message_id}",
+            headers=self._auth_header(),
+            params={"format": format_type, "metadataHeaders": ["From", "To", "Subject", "Date"]},
+            expected=(200,), transform=_shape,
+        )
+
+    def read_top_emails(self, n: int = 5, full_body: bool = False) -> Result:
+        listing = self.list_emails(n=n, unread_only=False)
+        if "error" in listing:
+            return listing
+        emails: List[Dict[str, Any]] = []
+        for msg in listing.get("result", []):
+            detail = self.get_email(msg["id"], full_body=full_body)
+            emails.append(detail.get("result", detail) if "error" not in detail else detail)
+        return {"ok": True, "result": emails}
diff --git a/craftos_integrations/integrations/google_calendar/INTEGRATION.md b/craftos_integrations/integrations/google_calendar/INTEGRATION.md
new file mode 100644
index 00000000..f4440020
--- /dev/null
+++ b/craftos_integrations/integrations/google_calendar/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Google Calendar — Integration Reference
+
+Schedule events, check free/busy, and create Google Meet links on the user's Google Calendar. Part of the Google Workspace bundle (shares OAuth shape with `gmail`, `google_drive`, `google_docs`).
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. Calendar will never push incoming changes. Don't promise the user "I'll notify you when X is scheduled."
+- **`calendar_id` defaults to `"primary"`** — the connected user's main calendar. Don't ask which calendar to use unless the user explicitly mentions a shared one. Other calendar IDs are email-like (e.g. `team@group.calendar.google.com`); list them via `list_calendars`.
+- **Event IDs are opaque Google strings.** Pull from `list_events` / `get_event`; never construct.
+- **Times are ISO 8601 with timezone** (e.g. `2026-05-20T09:00:00-04:00` or `...Z`). The integration knows the user's email (`cred.email`) but NOT their default timezone — if the user gives a bare time ("3pm"), the router must establish the timezone first.
+- **Recurring events expand on read.** `list_events` returns `singleEvents=true`-expanded instances, each with its own `id`. Deleting one instance does not affect the series.
+- **Meet links require `with_video_meeting=True`** on create (or a `conferenceData.createRequest` block). The returned `meetLink` is the share URL; don't construct meeting URLs by hand.
+- **Session-level facts:** `cred.email` is the connected account. Never ask the user for "your email" to invite themselves.
diff --git a/craftos_integrations/integrations/google_calendar/__init__.py b/craftos_integrations/integrations/google_calendar/__init__.py
new file mode 100644
index 00000000..43b1edf0
--- /dev/null
+++ b/craftos_integrations/integrations/google_calendar/__init__.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Google Calendar - granular Google integration.
+
+Connect just Calendar (without granting Gmail/Drive/YouTube scopes) by
+clicking Connect on the Google Calendar card. Credential is saved to
+``gcal.json``.
+
+See ``gmail.py`` for the canonical per-service shape - this file is
+structurally identical, differing only in scope, REST surface, and
+listener (Calendar doesn't poll for incoming messages).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    register_client,
+    register_handler,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._google_common import (
+    CALENDAR_SCOPES,
+    GoogleApiClientMixin,
+    GoogleCredential,
+    make_google_oauth,
+    run_google_login,
+    run_google_logout,
+    run_google_status,
+)
+
+logger = get_logger(__name__)
+
+CALENDAR_API_BASE = "https://www.googleapis.com/calendar/v3"
+
+
+GCAL = IntegrationSpec(
+    name="google_calendar",
+    cred_class=GoogleCredential,
+    cred_file="gcal.json",
+    platform_id="google_calendar",
+)
+
+
+# -----------------------------------------------------------------
+# Handler - auth flow only
+# -----------------------------------------------------------------
+
+@register_handler(GCAL.name)
+class GoogleCalendarHandler(IntegrationHandler):
+    spec = GCAL
+    display_name = "Google Calendar"
+    description = "Calendar events, availability, and Meet links"
+    auth_type = "oauth"
+    icon = "google_calendar"
+    fields: List = []
+
+    oauth = make_google_oauth(CALENDAR_SCOPES)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_login(self.spec, self.oauth, "Google Calendar")
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_logout(self.spec, "Google Calendar")
+
+    async def status(self) -> Tuple[bool, str]:
+        return await run_google_status(self.spec, "Google Calendar")
+
+
+# -----------------------------------------------------------------
+# Client - Calendar REST methods (no listener; Calendar isn't push-based)
+# -----------------------------------------------------------------
+
+@register_client
+class GoogleCalendarClient(GoogleApiClientMixin, BasePlatformClient):
+    spec = GCAL
+    PLATFORM_ID = GCAL.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[GoogleCredential] = None
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "Google Calendar does not support send_message - use create_meet_event"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def create_meet_event(self, calendar_id: str = "primary",
+                          event_data: Optional[Dict[str, Any]] = None) -> Result:
+        return http_request(
+            "POST", f"{CALENDAR_API_BASE}/calendars/{calendar_id}/events",
+            headers=self._headers(), params={"conferenceDataVersion": 1},
+            json=event_data or {},
+        )
+
+    def check_availability(self, calendar_id: str = "primary",
+                           time_min: Optional[str] = None,
+                           time_max: Optional[str] = None) -> Result:
+        return http_request(
+            "POST", f"{CALENDAR_API_BASE}/freeBusy",
+            headers=self._headers(),
+            json={"timeMin": time_min, "timeMax": time_max, "items": [{"id": calendar_id}]},
+            expected=(200,),
+        )
+
+    def list_events(self, calendar_id: str = "primary",
+                    time_min: Optional[str] = None,
+                    time_max: Optional[str] = None,
+                    max_results: int = 50) -> Result:
+        params: Dict[str, Any] = {
+            "maxResults": max_results,
+            "singleEvents": "true",
+            "orderBy": "startTime",
+        }
+        if time_min:
+            params["timeMin"] = time_min
+        if time_max:
+            params["timeMax"] = time_max
+        return http_request(
+            "GET", f"{CALENDAR_API_BASE}/calendars/{calendar_id}/events",
+            headers=self._auth_header(), params=params, expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
+
+    def get_event(self, event_id: str, calendar_id: str = "primary") -> Result:
+        return http_request(
+            "GET", f"{CALENDAR_API_BASE}/calendars/{calendar_id}/events/{event_id}",
+            headers=self._auth_header(), expected=(200,),
+        )
+
+    def delete_event(self, event_id: str, calendar_id: str = "primary") -> Result:
+        return http_request(
+            "DELETE", f"{CALENDAR_API_BASE}/calendars/{calendar_id}/events/{event_id}",
+            headers=self._auth_header(), expected=(204,),
+            transform=lambda _d: {"deleted": True, "event_id": event_id},
+        )
+
+    def list_calendars(self) -> Result:
+        return http_request(
+            "GET", f"{CALENDAR_API_BASE}/users/me/calendarList",
+            headers=self._auth_header(), expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
diff --git a/craftos_integrations/integrations/google_docs/INTEGRATION.md b/craftos_integrations/integrations/google_docs/INTEGRATION.md
new file mode 100644
index 00000000..a8108bdc
--- /dev/null
+++ b/craftos_integrations/integrations/google_docs/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Google Docs — Integration Reference
+
+Create, read, edit, and search Google Docs on the user's Drive. Part of the Google Workspace bundle (shares OAuth shape with `gmail`, `google_calendar`, `google_drive`).
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. Docs will never push incoming changes — purely request-response.
+- **Document IDs are 44+ char opaque strings** (embedded in URLs as `/document/d/{id}/edit`). Don't construct. Use `search_google_docs` (by title substring) or `list_google_docs` to discover.
+- **`append_to_google_doc` is not idempotent.** It reads the current end-index, then inserts. If the append errored but actually succeeded server-side, retrying duplicates the text. Verify with `get_google_doc_text` before retrying.
+- **`get_google_doc_text` flattens body text only.** Tables, images, and embedded objects are dropped. For structured reads use `get_google_doc` and walk the returned content tree.
+- **`replace_google_doc_text` is `replaceAllText`** — every occurrence in the body is swapped at once, with no preview. Confirm scope with the user before broad replacements.
+- **Session-level facts:** `cred.email` is the connected Google account. Never ask the user for it.
+- **Scope warning:** the integration uses the broad `auth/drive` scope (not the narrower `drive.file`) so it can see docs the user owns even when not created by the integration. This is why the OAuth consent screen may warn the user about an "unverified app."
diff --git a/craftos_integrations/integrations/google_docs/__init__.py b/craftos_integrations/integrations/google_docs/__init__.py
new file mode 100644
index 00000000..56531262
--- /dev/null
+++ b/craftos_integrations/integrations/google_docs/__init__.py
@@ -0,0 +1,246 @@
+# -*- coding: utf-8 -*-
+"""Google Docs - granular Google integration.
+
+Connect just Docs (without granting Gmail/Calendar/Drive/YouTube scopes)
+by clicking Connect on the Google Docs card. Credential is saved to
+``gdocs.json``.
+
+Same per-service shape as ``gmail.py`` / ``google_calendar.py`` /
+``google_drive.py``. Docs uses two API surfaces:
+  - ``docs.googleapis.com/v1`` for document content (read/write structured)
+  - ``drive.googleapis.com/v3`` for file-level ops (create/list/copy)
+The Docs scope ``auth/documents`` covers the docs API; we additionally
+request the full ``auth/drive`` scope so list/search can find docs the
+user already owns (the narrower ``drive.file`` scope only sees files the
+integration itself created, which is a frequent source of "I can see the
+doc in Drive but the agent can't" complaints).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    register_client,
+    register_handler,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._google_common import (
+    DOCS_SCOPES,
+    DRIVE_SCOPES,
+    GoogleApiClientMixin,
+    GoogleCredential,
+    make_google_oauth,
+    run_google_login,
+    run_google_logout,
+    run_google_status,
+)
+
+logger = get_logger(__name__)
+
+DOCS_API_BASE = "https://docs.googleapis.com/v1"
+DRIVE_API_BASE = "https://www.googleapis.com/drive/v3"
+
+# Docs needs both the documents scope (read/write doc bodies) AND
+# the full Drive scope so list/search hits docs the user already owns
+# in their Drive - not just those created by this integration.
+# Trade-off: this is a Google "restricted" scope; the OAuth consent
+# screen shows an "unverified app" warning until the app is verified.
+# Matches the scope shape used by google_drive.py.
+DOCS_AND_DRIVE_SCOPES = f"{DOCS_SCOPES} {DRIVE_SCOPES}"
+
+
+GDOCS = IntegrationSpec(
+    name="google_docs",
+    cred_class=GoogleCredential,
+    cred_file="gdocs.json",
+    platform_id="google_docs",
+)
+
+
+# -----------------------------------------------------------------
+# Handler - auth flow only
+# -----------------------------------------------------------------
+
+@register_handler(GDOCS.name)
+class GoogleDocsHandler(IntegrationHandler):
+    spec = GDOCS
+    display_name = "Google Docs"
+    description = "Read, edit, and create documents"
+    auth_type = "oauth"
+    icon = "google_docs"
+    fields: List = []
+
+    oauth = make_google_oauth(DOCS_AND_DRIVE_SCOPES)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_login(self.spec, self.oauth, "Google Docs")
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_logout(self.spec, "Google Docs")
+
+    async def status(self) -> Tuple[bool, str]:
+        return await run_google_status(self.spec, "Google Docs")
+
+
+# -----------------------------------------------------------------
+# Client - Docs REST methods (no listener)
+# -----------------------------------------------------------------
+
+@register_client
+class GoogleDocsClient(GoogleApiClientMixin, BasePlatformClient):
+    spec = GDOCS
+    PLATFORM_ID = GDOCS.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[GoogleCredential] = None
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "Google Docs does not support send_message"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def create_document(self, title: str) -> Result:
+        """Create a new blank Google Doc and return its metadata."""
+        return http_request(
+            "POST", f"{DOCS_API_BASE}/documents",
+            headers=self._headers(),
+            json={"title": title},
+            transform=lambda d: {
+                "document_id": d.get("documentId"),
+                "title": d.get("title"),
+                "url": f"https://docs.google.com/document/d/{d.get('documentId')}/edit",
+            },
+        )
+
+    def get_document(self, document_id: str) -> Result:
+        """Read a document's full structured content (body + headers/footers)."""
+        return http_request(
+            "GET", f"{DOCS_API_BASE}/documents/{document_id}",
+            headers=self._auth_header(), expected=(200,),
+        )
+
+    def get_document_text(self, document_id: str) -> Result:
+        """Plain-text view of a document - flattens the body into a single string."""
+        result = self.get_document(document_id)
+        if "error" in result:
+            return result
+        doc = result["result"]
+        text_parts: List[str] = []
+        for elem in (doc.get("body", {}).get("content", []) or []):
+            para = elem.get("paragraph")
+            if not para:
+                continue
+            for run in (para.get("elements") or []):
+                tr = run.get("textRun")
+                if tr and tr.get("content"):
+                    text_parts.append(tr["content"])
+        return {"ok": True, "result": {
+            "document_id": document_id,
+            "title": doc.get("title", ""),
+            "text": "".join(text_parts),
+        }}
+
+    def append_text(self, document_id: str, text: str) -> Result:
+        """Append text to the end of a document via batchUpdate."""
+        # Get the doc to find its current end-index for insertion.
+        result = self.get_document(document_id)
+        if "error" in result:
+            return result
+        body = result["result"].get("body", {})
+        end_index = body.get("content", [{}])[-1].get("endIndex", 1) if body.get("content") else 1
+        # Insert just before the trailing newline (endIndex - 1).
+        return http_request(
+            "POST", f"{DOCS_API_BASE}/documents/{document_id}:batchUpdate",
+            headers=self._headers(),
+            json={
+                "requests": [
+                    {"insertText": {
+                        "location": {"index": max(1, end_index - 1)},
+                        "text": text,
+                    }},
+                ],
+            },
+            expected=(200,),
+            transform=lambda _d: {"appended": True, "document_id": document_id},
+        )
+
+    def replace_text(self, document_id: str, find: str, replace: str,
+                     match_case: bool = False) -> Result:
+        """Find-and-replace across the entire document body."""
+        return http_request(
+            "POST", f"{DOCS_API_BASE}/documents/{document_id}:batchUpdate",
+            headers=self._headers(),
+            json={
+                "requests": [
+                    {"replaceAllText": {
+                        "containsText": {"text": find, "matchCase": match_case},
+                        "replaceText": replace,
+                    }},
+                ],
+            },
+            expected=(200,),
+            transform=lambda d: {
+                "document_id": document_id,
+                "occurrences_changed": (
+                    (d.get("replies") or [{}])[0]
+                    .get("replaceAllText", {})
+                    .get("occurrencesChanged", 0)
+                ),
+            },
+        )
+
+    def list_documents(self, max_results: int = 50) -> Result:
+        """List Google Docs files the user owns or has access to."""
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files", headers=self._auth_header(),
+            params={
+                "q": "mimeType='application/vnd.google-apps.document' and trashed=false",
+                "pageSize": max_results,
+                "fields": "files(id,name,modifiedTime,webViewLink)",
+                "orderBy": "modifiedTime desc",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("files", []),
+        )
+
+    def search_documents(self, query: str, max_results: int = 50) -> Result:
+        """Search for Google Docs by name. ``query`` is a fragment matched
+        against the document title."""
+        # Drive's q-query syntax: combine name contains with mimeType filter.
+        q = (
+            f"name contains '{query}' "
+            "and mimeType='application/vnd.google-apps.document' "
+            "and trashed=false"
+        )
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files", headers=self._auth_header(),
+            params={
+                "q": q,
+                "pageSize": max_results,
+                "fields": "files(id,name,modifiedTime,webViewLink)",
+                "orderBy": "modifiedTime desc",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("files", []),
+        )
+
+    def delete_document(self, document_id: str) -> Result:
+        """Delete a Google Doc (moves to Drive trash)."""
+        return http_request(
+            "DELETE", f"{DRIVE_API_BASE}/files/{document_id}",
+            headers=self._auth_header(), expected=(204,),
+            transform=lambda _d: {"deleted": True, "document_id": document_id},
+        )
diff --git a/craftos_integrations/integrations/google_drive/INTEGRATION.md b/craftos_integrations/integrations/google_drive/INTEGRATION.md
new file mode 100644
index 00000000..70520f27
--- /dev/null
+++ b/craftos_integrations/integrations/google_drive/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Google Drive — Integration Reference
+
+List, search, move, share, and delete files and folders in the user's Drive. Part of the Google Workspace bundle (shares OAuth shape with `gmail`, `google_calendar`, `google_docs`).
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. Drive will never push file-change notifications — purely request-response.
+- **File and folder IDs are opaque 44-char strings.** Don't construct. Use `search_drive` (free-form q-query), `find_drive_folder_by_name`, or `list_drive_files` to discover.
+- **`"root"` is the special folder ID** for the user's Drive root. To list a folder's contents, query `'{folder_id}' in parents and trashed = false` — the `trashed = false` predicate is critical, omitting it returns deleted files.
+- **Folders are files with `mimeType: "application/vnd.google-apps.folder"`.** Filtering by mimeType is the canonical way to separate them in search results.
+- **Sharing requires an email address, not a name or handle.** `share_drive_file` takes `emailAddress` + a role enum (`reader`, `commenter`, `writer`, `owner` — case-sensitive). Google's permission sync can lag a few seconds — don't assume the recipient sees it instantly.
+- **Move = re-parent.** `move_drive_file` adds new parent IDs and removes old ones in a single call. To move within Drive there's no "rename path"; the file just changes its `parents` array.
+- **Session-level facts:** `cred.email` is the connected account. Never ask the user for it.
diff --git a/craftos_integrations/integrations/google_drive/__init__.py b/craftos_integrations/integrations/google_drive/__init__.py
new file mode 100644
index 00000000..7a2e4d7d
--- /dev/null
+++ b/craftos_integrations/integrations/google_drive/__init__.py
@@ -0,0 +1,180 @@
+# -*- coding: utf-8 -*-
+"""Google Drive - granular Google integration.
+
+Connect just Drive (without granting Gmail/Calendar/YouTube scopes) by
+clicking Connect on the Google Drive card. Credential is saved to
+``gdrive.json``.
+
+Same per-service shape as ``gmail.py`` and ``google_calendar.py`` - the
+only file-level differences are the scope, the API base URL, and the
+REST surface.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    register_client,
+    register_handler,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._google_common import (
+    DRIVE_SCOPES,
+    GoogleApiClientMixin,
+    GoogleCredential,
+    make_google_oauth,
+    run_google_login,
+    run_google_logout,
+    run_google_status,
+)
+
+logger = get_logger(__name__)
+
+DRIVE_API_BASE = "https://www.googleapis.com/drive/v3"
+
+
+GDRIVE = IntegrationSpec(
+    name="google_drive",
+    cred_class=GoogleCredential,
+    cred_file="gdrive.json",
+    platform_id="google_drive",
+)
+
+
+# -----------------------------------------------------------------
+# Handler - auth flow only
+# -----------------------------------------------------------------
+
+@register_handler(GDRIVE.name)
+class GoogleDriveHandler(IntegrationHandler):
+    spec = GDRIVE
+    display_name = "Google Drive"
+    description = "Files, folders, and sharing"
+    auth_type = "oauth"
+    icon = "google_drive"
+    fields: List = []
+
+    oauth = make_google_oauth(DRIVE_SCOPES)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_login(self.spec, self.oauth, "Google Drive")
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_logout(self.spec, "Google Drive")
+
+    async def status(self) -> Tuple[bool, str]:
+        return await run_google_status(self.spec, "Google Drive")
+
+
+# -----------------------------------------------------------------
+# Client - Drive REST methods (no listener; Drive isn't push-based)
+# -----------------------------------------------------------------
+
+@register_client
+class GoogleDriveClient(GoogleApiClientMixin, BasePlatformClient):
+    spec = GDRIVE
+    PLATFORM_ID = GDRIVE.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[GoogleCredential] = None
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "Google Drive does not support send_message"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def list_drive_files(self, folder_id: str, fields: Optional[str] = None) -> Result:
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files", headers=self._auth_header(),
+            params={
+                "q": f"'{folder_id}' in parents and trashed = false",
+                "fields": fields or "files(id,name,mimeType,parents)",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("files", []),
+        )
+
+    def search_drive(self, query: str, max_results: int = 50,
+                     fields: Optional[str] = None) -> Result:
+        """Free-form search across all of Drive - uses Drive's q-query syntax."""
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files", headers=self._auth_header(),
+            params={
+                "q": query,
+                "pageSize": max_results,
+                "fields": fields or "files(id,name,mimeType,parents,modifiedTime)",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("files", []),
+        )
+
+    def create_drive_folder(self, name: str, parent_folder_id: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"name": name, "mimeType": "application/vnd.google-apps.folder"}
+        if parent_folder_id:
+            payload["parents"] = [parent_folder_id]
+        return http_request(
+            "POST", f"{DRIVE_API_BASE}/files", headers=self._headers(),
+            json=payload,
+        )
+
+    def get_drive_file(self, file_id: str, fields: Optional[str] = None) -> Result:
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files/{file_id}",
+            headers=self._auth_header(),
+            params={"fields": fields or "id,name,mimeType,parents,modifiedTime,webViewLink"},
+            expected=(200,),
+        )
+
+    def move_drive_file(self, file_id: str, add_parents: str, remove_parents: str) -> Result:
+        params: Dict[str, str] = {"addParents": add_parents, "fields": "id,parents"}
+        if remove_parents:
+            params["removeParents"] = remove_parents
+        return http_request(
+            "PATCH", f"{DRIVE_API_BASE}/files/{file_id}",
+            headers=self._auth_header(), params=params, expected=(200,),
+        )
+
+    def find_drive_folder_by_name(self, name: str,
+                                   parent_folder_id: Optional[str] = None) -> Result:
+        q_parts = [
+            f"name = '{name}'",
+            "mimeType = 'application/vnd.google-apps.folder'",
+            "trashed = false",
+        ]
+        if parent_folder_id:
+            q_parts.append(f"'{parent_folder_id}' in parents")
+        return http_request(
+            "GET", f"{DRIVE_API_BASE}/files", headers=self._auth_header(),
+            params={"q": " and ".join(q_parts), "fields": "files(id,name)"},
+            expected=(200,),
+            transform=lambda d: (d.get("files") or [None])[0],
+        )
+
+    def delete_drive_file(self, file_id: str) -> Result:
+        return http_request(
+            "DELETE", f"{DRIVE_API_BASE}/files/{file_id}",
+            headers=self._auth_header(), expected=(204,),
+            transform=lambda _d: {"deleted": True, "file_id": file_id},
+        )
+
+    def share_drive_file(self, file_id: str, email: str,
+                         role: str = "reader") -> Result:
+        """Grant a Drive permission. Roles: reader, commenter, writer, owner."""
+        return http_request(
+            "POST", f"{DRIVE_API_BASE}/files/{file_id}/permissions",
+            headers=self._headers(),
+            json={"type": "user", "role": role, "emailAddress": email},
+        )
diff --git a/craftos_integrations/integrations/google_youtube/INTEGRATION.md b/craftos_integrations/integrations/google_youtube/INTEGRATION.md
new file mode 100644
index 00000000..11e2cac1
--- /dev/null
+++ b/craftos_integrations/integrations/google_youtube/INTEGRATION.md
@@ -0,0 +1,16 @@
+# YouTube — Integration Reference
+
+Search YouTube, manage the user's subscriptions and playlists, post comments, and rate videos. Part of the Google Workspace bundle.
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. YouTube will never push new-video / new-comment notifications — purely request-response.
+- **ID formats are fixed and distinct — don't mix:**
+  - video IDs are 11-char strings (e.g. `dQw4w9WgXcQ`)
+  - channel IDs are 24-char strings starting with `UC...`
+  - playlist IDs start with `PL...` and are usually 34+ chars
+  - **subscription IDs ≠ channel IDs**
+- **`unsubscribe_from_youtube_channel` takes the SUBSCRIPTION ID,** not the channel ID. Get it from `list_my_youtube_subscriptions`. Passing a channel ID fails server-side.
+- **`rate_youtube_video` enum is `like` | `dislike` | `none`.** `"none"` is how you clear an existing rating — not deletion.
+- **Comments are top-level only.** `post_youtube_comment` does not support replies-to-comments. `get_youtube_video_comments` returns top-level comments most-recent first; thread expansion is not exposed.
+- **Session-level facts:** `cred.email` is the connected Google account; the user's own channel info is one `get_my_youtube_channel` call away — don't ask the user for their channel name or subscriber count.
diff --git a/craftos_integrations/integrations/google_youtube/__init__.py b/craftos_integrations/integrations/google_youtube/__init__.py
new file mode 100644
index 00000000..dc52a25b
--- /dev/null
+++ b/craftos_integrations/integrations/google_youtube/__init__.py
@@ -0,0 +1,234 @@
+# -*- coding: utf-8 -*-
+"""YouTube - granular Google integration.
+
+Connect just YouTube (without granting Gmail/Calendar/Drive/Docs scopes)
+by clicking Connect on the YouTube card. Credential is saved to
+``youtube.json``.
+
+Scopes used:
+  - ``youtube.readonly`` - list channels, fetch video metadata, search
+  - ``youtube.force-ssl`` - required for any write op (subscribe, comment,
+    rate, manage playlists). Same scope shape as the Workspace meta.
+
+The YouTube Data API v3 is the only surface used; everything goes through
+``https://www.googleapis.com/youtube/v3``.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    register_client,
+    register_handler,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._google_common import (
+    YOUTUBE_SCOPES,
+    GoogleApiClientMixin,
+    GoogleCredential,
+    make_google_oauth,
+    run_google_login,
+    run_google_logout,
+    run_google_status,
+)
+
+logger = get_logger(__name__)
+
+YOUTUBE_API_BASE = "https://www.googleapis.com/youtube/v3"
+
+
+YOUTUBE = IntegrationSpec(
+    name="google_youtube",
+    cred_class=GoogleCredential,
+    cred_file="youtube.json",
+    platform_id="google_youtube",
+)
+
+
+# -----------------------------------------------------------------
+# Handler - auth flow only
+# -----------------------------------------------------------------
+
+@register_handler(YOUTUBE.name)
+class YouTubeHandler(IntegrationHandler):
+    spec = YOUTUBE
+    display_name = "YouTube"
+    description = "Channels, videos, playlists, and subscriptions"
+    auth_type = "oauth"
+    icon = "google_youtube"
+    fields: List = []
+
+    oauth = make_google_oauth(YOUTUBE_SCOPES)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_login(self.spec, self.oauth, "YouTube")
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        return await run_google_logout(self.spec, "YouTube")
+
+    async def status(self) -> Tuple[bool, str]:
+        return await run_google_status(self.spec, "YouTube")
+
+
+# -----------------------------------------------------------------
+# Client - YouTube REST methods (no listener)
+# -----------------------------------------------------------------
+
+@register_client
+class YouTubeClient(GoogleApiClientMixin, BasePlatformClient):
+    spec = YOUTUBE
+    PLATFORM_ID = YOUTUBE.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[GoogleCredential] = None
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "YouTube does not support send_message"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def get_my_channel(self) -> Result:
+        """Return the authenticated user's channel (id, title, stats)."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/channels",
+            headers=self._auth_header(),
+            params={"part": "snippet,statistics,contentDetails", "mine": "true"},
+            expected=(200,),
+            transform=lambda d: (d.get("items") or [None])[0],
+        )
+
+    def search(self, query: str, max_results: int = 25,
+               type_filter: str = "video") -> Result:
+        """Search YouTube. ``type_filter`` is one of ``video|channel|playlist``."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/search",
+            headers=self._auth_header(),
+            params={
+                "part": "snippet",
+                "q": query,
+                "maxResults": max_results,
+                "type": type_filter,
+            },
+            expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
+
+    def get_video(self, video_id: str) -> Result:
+        """Full metadata for a single video (snippet + stats + content details)."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/videos",
+            headers=self._auth_header(),
+            params={"part": "snippet,statistics,contentDetails", "id": video_id},
+            expected=(200,),
+            transform=lambda d: (d.get("items") or [None])[0],
+        )
+
+    def list_my_subscriptions(self, max_results: int = 50) -> Result:
+        """Channels the authenticated user is subscribed to."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/subscriptions",
+            headers=self._auth_header(),
+            params={
+                "part": "snippet",
+                "mine": "true",
+                "maxResults": max_results,
+                "order": "alphabetical",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
+
+    def list_my_playlists(self, max_results: int = 50) -> Result:
+        """Playlists owned by the authenticated user."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/playlists",
+            headers=self._auth_header(),
+            params={"part": "snippet,contentDetails", "mine": "true", "maxResults": max_results},
+            expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
+
+    def list_playlist_items(self, playlist_id: str, max_results: int = 50) -> Result:
+        """Videos in a playlist."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/playlistItems",
+            headers=self._auth_header(),
+            params={"part": "snippet", "playlistId": playlist_id, "maxResults": max_results},
+            expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
+
+    def subscribe(self, channel_id: str) -> Result:
+        """Subscribe the authenticated user to a channel."""
+        return http_request(
+            "POST", f"{YOUTUBE_API_BASE}/subscriptions",
+            headers=self._headers(),
+            params={"part": "snippet"},
+            json={"snippet": {"resourceId": {"kind": "youtube#channel", "channelId": channel_id}}},
+        )
+
+    def unsubscribe(self, subscription_id: str) -> Result:
+        """Remove a subscription. ``subscription_id`` is the id returned by
+        ``list_my_subscriptions`` (NOT the channel id - it's the subscription
+        relationship's own id)."""
+        return http_request(
+            "DELETE", f"{YOUTUBE_API_BASE}/subscriptions",
+            headers=self._auth_header(),
+            params={"id": subscription_id},
+            expected=(204,),
+            transform=lambda _d: {"unsubscribed": True, "subscription_id": subscription_id},
+        )
+
+    def rate_video(self, video_id: str, rating: str) -> Result:
+        """Like / dislike / clear rating. ``rating`` is one of
+        ``like|dislike|none``."""
+        return http_request(
+            "POST", f"{YOUTUBE_API_BASE}/videos/rate",
+            headers=self._auth_header(),
+            params={"id": video_id, "rating": rating},
+            expected=(204,),
+            transform=lambda _d: {"video_id": video_id, "rating": rating},
+        )
+
+    def post_comment(self, video_id: str, text: str) -> Result:
+        """Post a top-level comment on a video."""
+        return http_request(
+            "POST", f"{YOUTUBE_API_BASE}/commentThreads",
+            headers=self._headers(),
+            params={"part": "snippet"},
+            json={
+                "snippet": {
+                    "videoId": video_id,
+                    "topLevelComment": {"snippet": {"textOriginal": text}},
+                },
+            },
+        )
+
+    def get_video_comments(self, video_id: str, max_results: int = 50) -> Result:
+        """Top-level comments on a video, most-recent first."""
+        return http_request(
+            "GET", f"{YOUTUBE_API_BASE}/commentThreads",
+            headers=self._auth_header(),
+            params={
+                "part": "snippet",
+                "videoId": video_id,
+                "maxResults": max_results,
+                "order": "time",
+                "textFormat": "plainText",
+            },
+            expected=(200,),
+            transform=lambda d: d.get("items", []),
+        )
diff --git a/craftos_integrations/integrations/jira/INTEGRATION.md b/craftos_integrations/integrations/jira/INTEGRATION.md
new file mode 100644
index 00000000..162b6675
--- /dev/null
+++ b/craftos_integrations/integrations/jira/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Jira — Integration Reference
+
+REST integration for Jira Cloud / Server via API token or OAuth. JQL search, issue CRUD, comments, transitions, label-based polling.
+
+## Essentials
+
+- **Issue identifier is the `key` (e.g. `PROJ-123`), not a numeric ID.** Every action expects `issue_key`. Resolve from `search_jira_issues` first if the user gives only a number or a title.
+- **Assignee is an `account_id`, not a display name.** Use `search_jira_users` to translate `"Alice Chen"` → account_id before calling `assign_jira_issue`. Pass empty string to unassign.
+- **Comments are Atlassian Document Format (ADF) on the wire.** The integration auto-converts plain text on send and auto-extracts plain text on read — pass plain strings, don't construct ADF JSON.
+- **`watch_tag` and `watch_labels` config silently drop traffic.** If `watch_labels` is non-empty, only issues with at least one matching label trigger the listener. If `watch_tag` is set, only comments containing that tag dispatch (the instruction is the text AFTER the tag). If incoming events stop, check both.
+- **Session-level facts:** `cred.domain`, `cred.email`, `cred.cloud_id` (OAuth) are stored at login. Don't ask the user for their Jira site.
+- **Auth errors don't recover by retry.** `401` = bad/expired token; `403` = account lacks API permission; `404` = wrong domain. Ask the user to verify credentials or request admin access.
diff --git a/craftos_integrations/integrations/jira/__init__.py b/craftos_integrations/integrations/jira/__init__.py
new file mode 100644
index 00000000..3d42eb54
--- /dev/null
+++ b/craftos_integrations/integrations/jira/__init__.py
@@ -0,0 +1,697 @@
+# -*- coding: utf-8 -*-
+"""Jira integration - handler + client + credential."""
+from __future__ import annotations
+
+import asyncio
+import base64
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    save_config,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+JIRA_CLOUD_API = "https://api.atlassian.com/ex/jira"
+POLL_INTERVAL = 10
+RETRY_DELAY = 15
+
+
+@dataclass
+class JiraCredential:
+    domain: str = ""
+    email: str = ""
+    api_token: str = ""
+    cloud_id: str = ""
+    access_token: str = ""
+    refresh_token: str = ""
+    token_expiry: float = 0.0
+    site_url: str = ""
+
+
+@dataclass
+class JiraConfig:
+    """Runtime knobs separate from the credential. Persisted as
+    ``jira_config.json`` next to ``jira.json``."""
+    watch_tag: str = ""
+    watch_labels: List[str] = field(default_factory=list)
+
+
+JIRA = IntegrationSpec(
+    name="jira",
+    cred_class=JiraCredential,
+    cred_file="jira.json",
+    platform_id="jira",
+)
+
+
+def _jira_config_file() -> str:
+    """``jira.json`` → ``jira_config.json``."""
+    stem = JIRA.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(JIRA.name)
+class JiraHandler(IntegrationHandler):
+    spec = JIRA
+    display_name = "Jira"
+    description = "Issue tracking and project management"
+    auth_type = "token"
+    icon = "jira"
+    connect_help = [
+        "Domain → your Jira URL host (e.g. mycompany.atlassian.net)",
+        "Email → the address you log into Jira with",
+        "API Token: open id.atlassian.com/manage-profile/security/api-tokens",
+        "Click 'Create API token', label it (e.g. 'CraftBot'), copy the value",
+    ]
+    fields = [
+        {"key": "domain", "label": "Jira Domain", "placeholder": "mycompany.atlassian.net", "password": False},
+        {"key": "email", "label": "Email", "placeholder": "you@example.com", "password": False},
+        {"key": "api_token", "label": "API Token", "placeholder": "Enter Jira API token", "password": True},
+    ]
+    config_class = JiraConfig
+    config_fields = [
+        {"key": "watch_tag", "label": "Watch tag", "type": "text",
+         "placeholder": "@craftbot",
+         "help": "Trigger keyword in issue comments. Leave empty to react to all updates."},
+        {"key": "watch_labels", "label": "Watched labels", "type": "list",
+         "placeholder": "bug",
+         "help": "Comma-separated. Leave empty to watch issues with any label."},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 3:
+            return False, (
+                "Usage: /jira login <domain> <email> <api_token>\n"
+                "Get an API token from https://id.atlassian.com/manage-profile/security/api-tokens"
+            )
+        domain, email, api_token = args[0], args[1], args[2]
+
+        clean_domain = domain.strip().rstrip("/")
+        if clean_domain.startswith("https://"):
+            clean_domain = clean_domain[len("https://"):]
+        if clean_domain.startswith("http://"):
+            clean_domain = clean_domain[len("http://"):]
+        if "." not in clean_domain:
+            clean_domain = f"{clean_domain}.atlassian.net"
+
+        email = email.strip()
+        api_token = api_token.strip()
+
+        raw_auth = base64.b64encode(f"{email}:{api_token}".encode()).decode()
+        auth_headers = {"Authorization": f"Basic {raw_auth}", "Accept": "application/json"}
+
+        data = None
+        last_status = 0
+        for api_ver in ("3", "2"):
+            url = f"https://{clean_domain}/rest/api/{api_ver}/myself"
+            logger.info(f"[Jira] Trying {url} with email={email}")
+            try:
+                r = httpx.get(url, headers=auth_headers, timeout=15, follow_redirects=True)
+            except httpx.ConnectError:
+                return False, f"Cannot connect to https://{clean_domain} - check the domain name."
+            except Exception as e:
+                return False, f"Jira connection error: {e}"
+            if r.status_code == 200:
+                data = r.json()
+                break
+            logger.warning(f"[Jira] API v{api_ver} returned HTTP {r.status_code}: {r.text[:300]}")
+            last_status = r.status_code
+
+        if data is None:
+            hints = [f"Tried: https://{clean_domain}/rest/api/3/myself"]
+            if last_status == 401:
+                hints.append("Ensure you are using an API token, not your account password.")
+                hints.append("The email must match your Atlassian account email exactly.")
+                hints.append("Generate a token at: https://id.atlassian.com/manage-profile/security/api-tokens")
+            elif last_status == 403:
+                hints.append("Your account may not have REST API access. Check Jira permissions.")
+            elif last_status == 404:
+                hints.append(f"Domain '{clean_domain}' not reachable or has no REST API.")
+            hint_str = "\n".join(f"  - {h}" for h in hints)
+            return False, f"Jira auth failed (HTTP {last_status}).\n{hint_str}"
+
+        save_credential(self.spec.cred_file, JiraCredential(
+            domain=clean_domain,
+            email=email,
+            api_token=api_token,
+        ))
+        display_name = data.get("displayName", email)
+        return True, f"Jira connected as {display_name} ({clean_domain})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Jira credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Jira credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Jira: Not connected"
+        cred = load_credential(self.spec.cred_file, JiraCredential)
+        if not cred:
+            return True, "Jira: Not connected"
+        domain = cred.domain or cred.site_url or "unknown"
+        email = cred.email or "OAuth"
+        cfg = load_config(_jira_config_file(), JiraConfig) or JiraConfig()
+        label_info = f" [watching: {', '.join(cfg.watch_labels)}]" if cfg.watch_labels else ""
+        return True, f"Jira: Connected\n  - {email} ({domain}){label_info}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class JiraClient(BasePlatformClient):
+    spec = JIRA
+    PLATFORM_ID = JIRA.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[JiraCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._last_poll_time: Optional[str] = None
+        self._seen_issue_keys: set = set()
+        self._catchup_done: bool = False
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> JiraCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, JiraCredential)
+        if self._cred is None:
+            raise RuntimeError("No Jira credentials. Use /jira login first.")
+        return self._cred
+
+    def _is_oauth(self) -> bool:
+        cred = self._load()
+        return bool(cred.cloud_id and cred.access_token)
+
+    def _base_url(self) -> str:
+        cred = self._load()
+        if cred.cloud_id:
+            return f"{JIRA_CLOUD_API}/{cred.cloud_id}/rest/api/3"
+        if cred.domain:
+            domain = cred.domain.rstrip("/")
+            if not domain.startswith("http"):
+                domain = f"https://{domain}"
+            return f"{domain}/rest/api/3"
+        raise RuntimeError("No Jira domain or cloud_id configured.")
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+        if cred.cloud_id and cred.access_token:
+            headers["Authorization"] = f"Bearer {cred.access_token}"
+        elif cred.email and cred.api_token:
+            raw = f"{cred.email}:{cred.api_token}"
+            headers["Authorization"] = f"Basic {base64.b64encode(raw.encode()).decode()}"
+        else:
+            raise RuntimeError("Incomplete Jira credentials.")
+        return headers
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return await self.add_comment(recipient, text)
+
+    # ----- Watch labels / tag (read from jira_config.json) -----
+
+    def _config(self) -> JiraConfig:
+        return load_config(_jira_config_file(), JiraConfig) or JiraConfig()
+
+    def get_watch_labels(self) -> List[str]:
+        return list(self._config().watch_labels)
+
+    def set_watch_labels(self, labels: List[str]) -> None:
+        cfg = self._config()
+        cfg.watch_labels = [lbl.strip() for lbl in labels if lbl.strip()]
+        save_config(_jira_config_file(), cfg)
+        logger.info(f"[JIRA] Watch labels set to: {cfg.watch_labels or '(all issues)'}")
+
+    def add_watch_label(self, label: str) -> None:
+        cfg = self._config()
+        label = label.strip()
+        if label and label not in cfg.watch_labels:
+            cfg.watch_labels.append(label)
+            save_config(_jira_config_file(), cfg)
+
+    def remove_watch_label(self, label: str) -> None:
+        cfg = self._config()
+        label = label.strip()
+        if label in cfg.watch_labels:
+            cfg.watch_labels.remove(label)
+            save_config(_jira_config_file(), cfg)
+
+    def get_watch_tag(self) -> str:
+        return self._config().watch_tag
+
+    def set_watch_tag(self, tag: str) -> None:
+        cfg = self._config()
+        cfg.watch_tag = tag.strip()
+        save_config(_jira_config_file(), cfg)
+
+    # ----- Listening -----
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        self._load()
+
+        me = await self.get_myself()
+        if "error" in me:
+            raise RuntimeError(f"Invalid Jira credentials: {me.get('error')}")
+        display = me.get("result", {}).get("displayName", "unknown")
+        logger.info(f"[JIRA] Authenticated as: {display}")
+
+        self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
+        self._catchup_done = True
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    async def _poll_loop(self) -> None:
+        while self._listening:
+            try:
+                await self._check_updates()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[JIRA] Poll error: {e}")
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    async def _check_updates(self) -> None:
+        if not self._last_poll_time:
+            return
+
+        self._load()  # ensure credentials are loaded; required by _base_url()/_headers()
+        cfg = self._config()
+        jql_parts = [f'updated >= "{self._last_poll_time}"']
+        if cfg.watch_labels:
+            label_clauses = " OR ".join(f'labels = "{lbl}"' for lbl in cfg.watch_labels)
+            jql_parts.append(f"({label_clauses})")
+        jql = " AND ".join(jql_parts) + " ORDER BY updated ASC"
+
+        result = await arequest(
+            "POST", f"{self._base_url()}/search/jql",
+            headers=self._headers(),
+            json={
+                "jql": jql,
+                "maxResults": 50,
+                "fields": ["summary", "status", "assignee", "reporter", "labels", "updated", "comment", "issuetype", "priority", "project"],
+            },
+            timeout=30.0,
+            expected=(200,),
+        )
+        if "error" in result:
+            if "401" in result["error"]:
+                logger.warning("[JIRA] Authentication expired (401)")
+            else:
+                logger.warning(f"[JIRA] Search API {result['error']}")
+            return
+
+        for issue in (result["result"] or {}).get("issues", []):
+            issue_key = issue.get("key", "")
+            updated = issue.get("fields", {}).get("updated", "")
+            dedup_key = f"{issue_key}:{updated}"
+            if dedup_key in self._seen_issue_keys:
+                continue
+            self._seen_issue_keys.add(dedup_key)
+            await self._dispatch_issue(issue)
+
+        self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M")
+        if len(self._seen_issue_keys) > 500:
+            self._seen_issue_keys = set(list(self._seen_issue_keys)[-200:])
+
+    async def _dispatch_issue(self, issue: Dict[str, Any]) -> None:
+        if not self._message_callback:
+            return
+
+        cfg = self._config()
+        fields_data = issue.get("fields", {})
+        issue_key = issue.get("key", "")
+        summary = fields_data.get("summary", "")
+        status_name = (fields_data.get("status") or {}).get("name", "")
+        issue_type = (fields_data.get("issuetype") or {}).get("name", "")
+        priority = (fields_data.get("priority") or {}).get("name", "")
+        project_key = (fields_data.get("project") or {}).get("key", "")
+        labels = fields_data.get("labels", [])
+
+        assignee = fields_data.get("assignee") or {}
+        assignee_name = assignee.get("displayName", "Unassigned")
+        reporter = fields_data.get("reporter") or {}
+        reporter_name = reporter.get("displayName", "Unknown")
+        comments = (fields_data.get("comment") or {}).get("comments", [])
+
+        watch_tag = cfg.watch_tag
+        if watch_tag:
+            matching_comment = None
+            tag_lower = watch_tag.lower()
+            for comment in reversed(comments):
+                comment_body = _extract_adf_text(comment.get("body", {}))
+                if tag_lower in comment_body.lower():
+                    comment_id = comment.get("id", "")
+                    comment_dedup = f"{issue_key}:comment:{comment_id}"
+                    if comment_dedup in self._seen_issue_keys:
+                        continue
+                    self._seen_issue_keys.add(comment_dedup)
+                    matching_comment = comment
+                    break
+
+            if matching_comment is None:
+                return
+
+            comment_author = (matching_comment.get("author") or {}).get("displayName", "Unknown")
+            comment_author_id = (matching_comment.get("author") or {}).get("accountId", "")
+            comment_body = _extract_adf_text(matching_comment.get("body", {}))
+            idx = comment_body.lower().find(tag_lower)
+            instruction = comment_body[idx + len(watch_tag):].strip() if idx >= 0 else comment_body
+
+            text_parts = [
+                f"[{issue_key}] {summary}",
+                f"Status: {status_name} | Assignee: {assignee_name}",
+                f"Comment by {comment_author}: {instruction or comment_body}",
+            ]
+
+            timestamp = None
+            try:
+                timestamp = datetime.fromisoformat(matching_comment.get("created", "").replace("Z", "+00:00"))
+            except Exception:
+                pass
+
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=comment_author_id,
+                sender_name=comment_author,
+                text="\n".join(text_parts),
+                channel_id=project_key,
+                channel_name=f"{project_key} ({issue_type})",
+                message_id=f"{issue_key}:{matching_comment.get('id', '')}",
+                timestamp=timestamp,
+                raw={
+                    "issue": issue,
+                    "trigger": "comment_tag",
+                    "tag": watch_tag,
+                    "instruction": instruction or comment_body,
+                    "comment": matching_comment,
+                },
+            ))
+            return
+
+        text_parts = [
+            f"[{issue_key}] {summary}",
+            f"Type: {issue_type} | Priority: {priority} | Status: {status_name}",
+            f"Project: {project_key} | Assignee: {assignee_name}",
+        ]
+        if labels:
+            text_parts.append(f"Labels: {', '.join(labels)}")
+        if comments:
+            latest = comments[-1]
+            cb = _extract_adf_text(latest.get("body", {}))
+            ca = (latest.get("author") or {}).get("displayName", "")
+            if cb:
+                text_parts.append(f"Latest comment by {ca}: {cb[:200]}")
+
+        timestamp = None
+        try:
+            timestamp = datetime.fromisoformat(fields_data.get("updated", "").replace("Z", "+00:00"))
+        except Exception:
+            pass
+
+        await self._message_callback(PlatformMessage(
+            platform=self.spec.platform_id,
+            sender_id=reporter.get("accountId", ""),
+            sender_name=reporter_name,
+            text="\n".join(text_parts),
+            channel_id=project_key,
+            channel_name=f"{project_key} ({issue_type})",
+            message_id=issue_key,
+            timestamp=timestamp,
+            raw=issue,
+        ))
+
+    # ----- REST API -----
+
+    async def get_myself(self) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/myself",
+            headers=self._headers(),
+            expected=(200,),
+            transform=lambda d: {
+                "accountId": d.get("accountId"),
+                "displayName": d.get("displayName"),
+                "emailAddress": d.get("emailAddress", ""),
+                "active": d.get("active", True),
+            },
+        )
+
+    async def search_issues(self, jql: str, max_results: int = 50, fields_list: Optional[List[str]] = None) -> Result:
+        payload: Dict[str, Any] = {"jql": jql, "maxResults": min(max_results, 100)}
+        if fields_list:
+            payload["fields"] = fields_list
+        return await arequest(
+            "POST", f"{self._base_url()}/search/jql",
+            headers=self._headers(),
+            json=payload,
+            timeout=30.0,
+            expected=(200,),
+            transform=lambda d: {"total": d.get("total", 0), "issues": d.get("issues", [])},
+        )
+
+    async def get_issue(self, issue_key: str, fields_list: Optional[List[str]] = None) -> Result:
+        params: Dict[str, Any] = {}
+        if fields_list:
+            params["fields"] = ",".join(fields_list)
+        return await arequest(
+            "GET", f"{self._base_url()}/issue/{issue_key}",
+            headers=self._headers(),
+            params=params,
+            expected=(200,),
+        )
+
+    async def create_issue(self, project_key: str, summary: str, issue_type: str = "Task",
+                           description: Optional[str] = None, assignee_id: Optional[str] = None,
+                           labels: Optional[List[str]] = None, priority: Optional[str] = None,
+                           extra_fields: Optional[Dict[str, Any]] = None) -> Result:
+        fields_payload: Dict[str, Any] = {
+            "project": {"key": project_key},
+            "summary": summary,
+            "issuetype": {"name": issue_type},
+        }
+        if description:
+            fields_payload["description"] = _text_to_adf(description)
+        if assignee_id:
+            fields_payload["assignee"] = {"accountId": assignee_id}
+        if labels:
+            fields_payload["labels"] = labels
+        if priority:
+            fields_payload["priority"] = {"name": priority}
+        if extra_fields:
+            fields_payload.update(extra_fields)
+
+        return await arequest(
+            "POST", f"{self._base_url()}/issue",
+            headers=self._headers(),
+            json={"fields": fields_payload},
+            transform=lambda d: {"id": d.get("id"), "key": d.get("key"), "self": d.get("self")},
+        )
+
+    async def update_issue(self, issue_key: str, fields_update: Dict[str, Any]) -> Result:
+        return await arequest(
+            "PUT", f"{self._base_url()}/issue/{issue_key}",
+            headers=self._headers(),
+            json={"fields": fields_update},
+            expected=(204,),
+            transform=lambda _d: {"updated": True, "key": issue_key},
+        )
+
+    async def add_comment(self, issue_key: str, body: str) -> Result:
+        return await arequest(
+            "POST", f"{self._base_url()}/issue/{issue_key}/comment",
+            headers=self._headers(),
+            json={"body": _text_to_adf(body)},
+            transform=lambda d: {"id": d.get("id"), "created": d.get("created"), "author": (d.get("author") or {}).get("displayName", "")},
+        )
+
+    async def get_transitions(self, issue_key: str) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/issue/{issue_key}/transitions",
+            headers=self._headers(),
+            expected=(200,),
+            transform=lambda d: {"transitions": [
+                {"id": t.get("id"), "name": t.get("name"), "to": (t.get("to") or {}).get("name", "")}
+                for t in d.get("transitions", [])
+            ]},
+        )
+
+    async def transition_issue(self, issue_key: str, transition_id: str, comment: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"transition": {"id": transition_id}}
+        if comment:
+            payload["update"] = {"comment": [{"add": {"body": _text_to_adf(comment)}}]}
+        return await arequest(
+            "POST", f"{self._base_url()}/issue/{issue_key}/transitions",
+            headers=self._headers(),
+            json=payload,
+            expected=(204,),
+            transform=lambda _d: {"transitioned": True, "key": issue_key},
+        )
+
+    async def assign_issue(self, issue_key: str, account_id: Optional[str] = None) -> Result:
+        return await arequest(
+            "PUT", f"{self._base_url()}/issue/{issue_key}/assignee",
+            headers=self._headers(),
+            json={"accountId": account_id},
+            expected=(204,),
+            transform=lambda _d: {"assigned": True, "key": issue_key},
+        )
+
+    async def get_projects(self, max_results: int = 50) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/project/search",
+            headers=self._headers(),
+            params={"maxResults": max_results},
+            expected=(200,),
+            transform=lambda d: {"projects": [
+                {"id": p.get("id"), "key": p.get("key"), "name": p.get("name"), "style": p.get("style", "")}
+                for p in d.get("values", [])
+            ]},
+        )
+
+    async def search_users(self, query: str, max_results: int = 20) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/user/search",
+            headers=self._headers(),
+            params={"query": query, "maxResults": max_results},
+            expected=(200,),
+            transform=lambda d: {"users": [
+                {"accountId": u.get("accountId"), "displayName": u.get("displayName"), "emailAddress": u.get("emailAddress", ""), "active": u.get("active", True)}
+                for u in d
+            ]},
+        )
+
+    async def get_issue_comments(self, issue_key: str, max_results: int = 50) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/issue/{issue_key}/comment",
+            headers=self._headers(),
+            params={"maxResults": max_results, "orderBy": "-created"},
+            expected=(200,),
+            transform=lambda d: {
+                "comments": [
+                    {"id": c.get("id"), "author": (c.get("author") or {}).get("displayName", ""), "body": _extract_adf_text(c.get("body", {})), "created": c.get("created"), "updated": c.get("updated")}
+                    for c in d.get("comments", [])
+                ],
+                "total": d.get("total", 0),
+            },
+        )
+
+    async def get_statuses(self, project_key: str) -> Result:
+        return await arequest(
+            "GET", f"{self._base_url()}/project/{project_key}/statuses",
+            headers=self._headers(),
+            expected=(200,),
+        )
+
+    async def add_labels(self, issue_key: str, labels: List[str]) -> Result:
+        return await arequest(
+            "PUT", f"{self._base_url()}/issue/{issue_key}",
+            headers=self._headers(),
+            json={"update": {"labels": [{"add": label} for label in labels]}},
+            expected=(204,),
+            transform=lambda _d: {"labels_added": labels, "key": issue_key},
+        )
+
+    async def remove_labels(self, issue_key: str, labels: List[str]) -> Result:
+        return await arequest(
+            "PUT", f"{self._base_url()}/issue/{issue_key}",
+            headers=self._headers(),
+            json={"update": {"labels": [{"remove": label} for label in labels]}},
+            expected=(204,),
+            transform=lambda _d: {"labels_removed": labels, "key": issue_key},
+        )
+
+
+# -----------------------------------------------------------------
+# ADF helpers
+# -----------------------------------------------------------------
+
+def _text_to_adf(text: str) -> Dict[str, Any]:
+    paragraphs = text.split("\n")
+    content = []
+    for para in paragraphs:
+        content.append({
+            "type": "paragraph",
+            "content": [{"type": "text", "text": para}] if para else [],
+        })
+    return {"version": 1, "type": "doc", "content": content}
+
+
+def _extract_adf_text(adf: Dict[str, Any]) -> str:
+    if not isinstance(adf, dict):
+        return str(adf) if adf else ""
+    parts: List[str] = []
+
+    def _walk(node):
+        if isinstance(node, dict):
+            if node.get("type") == "text":
+                parts.append(node.get("text", ""))
+            for child in node.get("content", []):
+                _walk(child)
+        elif isinstance(node, list):
+            for item in node:
+                _walk(item)
+
+    _walk(adf)
+    return " ".join(parts)
diff --git a/craftos_integrations/integrations/lark/INTEGRATION.md b/craftos_integrations/integrations/lark/INTEGRATION.md
new file mode 100644
index 00000000..389cbb1b
--- /dev/null
+++ b/craftos_integrations/integrations/lark/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Lark — Integration Reference
+
+Lark (Feishu) bot integration. Messages, calendar, drive, chat search. Uses the `lark_oapi` SDK with a WebSocket event stream.
+
+## Essentials
+
+- **No "self" alias.** Lark doesn't model a user-to-self relationship for a bot account. Specify a recipient explicitly.
+- **Recipient resolution is type-tagged.** `send_lark_message` takes a `receive_id_type` arg: one of `open_id` (default), `user_id`, `email`, `chat_id`, `union_id`. If sending by email, set `receive_id_type="email"` (don't try to embed the email in `open_id`). If you only have an email, use `get_lark_user_by_email` to discover the `open_id`.
+- **Identity formats:** `open_id` starts with `ou_...`, `chat_id` starts with `oc_...`. Different prefixes mean different lookup paths — don't pass them interchangeably.
+- **Message `content` is a JSON-encoded STRING**, not a JSON object. For a plain text message, the value is `{"text": "Hello"}` serialised to string (so the actual content arg is the string `'{"text": "Hello"}'`). The action's example shows the right shape — match it.
+- **Critical: app must be approved by the tenant admin.** The WebSocket will connect fine even if the current app version is unapproved, but events will NOT arrive. If incoming messages aren't flowing, that's the first thing to check — direct the user to their Lark admin.
+- **Token refresh is automatic** (2-hour TTL, refreshed within 60s of expiry). No manual intervention.
+- **Session-level facts the integration knows:** `app_id`, `bot_id`. Use `get_lark_bot_info` rather than asking.
diff --git a/craftos_integrations/integrations/lark/__init__.py b/craftos_integrations/integrations/lark/__init__.py
new file mode 100644
index 00000000..55f7625c
--- /dev/null
+++ b/craftos_integrations/integrations/lark/__init__.py
@@ -0,0 +1,412 @@
+# -*- coding: utf-8 -*-
+"""Lark integration - bidirectional messaging.
+
+Lark is ByteDance's enterprise messaging platform (the China-region twin
+``Feishu`` shares the API; the only difference is the API host). This
+integration targets **global Lark** (``open.larksuite.com``) with a
+custom-app, tenant-access-token auth flow.
+
+Sending: REST via ``/im/v1/messages`` with an auto-refreshing
+``tenant_access_token`` (2-hour TTL, refreshed within 60s of expiry).
+
+Receiving: persistent-connection WebSocket via the official ``lark-oapi``
+SDK. The SDK's blocking ``Client.start()`` runs on a daemon thread and
+events are dispatched back to the agent's asyncio loop via
+``run_coroutine_threadsafe``. Auto-reconnect is delegated to the SDK.
+
+Setup gotcha worth knowing up-front: events do **not** flow until the
+app version is approved by the tenant admin. The WS will connect and
+authenticate (no errors) but messages won't arrive until approval lands.
+
+Auth flow:
+  1. User creates a Custom App at ``open.larksuite.com/app``.
+  2. Adds the Bot feature, subscribes to ``im.message.receive_v1``, picks
+     'Receive callbacks through persistent connection' as subscription mode.
+  3. Enables permissions: ``im:message``, ``im:message.p2p_msg``,
+     ``im:message.group_at_msg:readonly``.
+  4. Submits a version for tenant admin approval.
+  5. Grabs App ID + App Secret from Credentials & Basic Info.
+  6. CraftBot mints a ``tenant_access_token`` via the
+     ``/open-apis/auth/v3/tenant_access_token/internal`` endpoint and
+     refreshes it before the 2-hour expiry on every send.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._lark_common import (
+    LARK_API_BASE,
+    LarkCredential,
+    make_headers,
+    validate_and_mint_token,
+)
+
+logger = get_logger(__name__)
+
+
+LARK = IntegrationSpec(
+    name="lark",
+    cred_class=LarkCredential,
+    cred_file="lark.json",
+    platform_id="lark",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(LARK.name)
+class LarkHandler(IntegrationHandler):
+    spec = LARK
+    display_name = "Lark"
+    description = "Two-way messaging via Lark (send + receive)"
+    auth_type = "token"
+    icon = "lark"
+    connect_help = [
+        "Open Lark Developer Console: open.larksuite.com/app and sign in",
+        "Create Custom App → give it a name",
+        "Add Features (left sidebar) → Bot → Add",
+        "Events & Callbacks → Event Configuration → Subscription Mode: select 'Receive callbacks through persistent connection'",
+        "Events & Callbacks → Event Configuration → Add Event: subscribe to 'im.message.receive_v1' (Receive Message) - without this, no DMs reach CraftBot",
+        "Events & Callbacks → Encryption Strategy: leave Encryption Key empty (this integration does not yet support encrypted events)",
+        "Permissions & Scopes → enable: im:message, im:message.p2p_msg, im:message.group_at_msg:readonly (the last is for group @-mentions and only appears after Bot is added)",
+        "Version Management → Create Version → submit for tenant admin approval - events do NOT flow until the version is Released",
+        "Credentials & Basic Info → copy App ID + App Secret and paste them below",
+    ]
+    fields = [
+        {"key": "app_id", "label": "App ID",
+         "placeholder": "cli_xxxxxxxxxx", "password": False},
+        {"key": "app_secret", "label": "App Secret",
+         "placeholder": "From Credentials tab", "password": True},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 2:
+            return False, ("Usage: /lark login <app_id> <app_secret>\n"
+                           "Get from open.larksuite.com/app → your app → Credentials tab.")
+        app_id, app_secret = args[0], args[1]
+
+        token, token_expires_at, err = validate_and_mint_token(app_id, app_secret)
+        if err:
+            return False, err
+
+        # Best-effort: fetch bot info so we can show the bot name in status().
+        # Falls back gracefully if the call fails (e.g. bot capability not
+        # enabled yet on the app).
+        bot_name = ""
+        bot_open_id = ""
+        info = http_request(
+            "GET", f"{LARK_API_BASE}/bot/v3/info",
+            headers={"Authorization": f"Bearer {token}"},
+            expected=(200,),
+        )
+        if "error" not in info:
+            bot = info.get("result", {}).get("bot", {})
+            bot_name = bot.get("app_name", "")
+            bot_open_id = bot.get("open_id", "")
+
+        save_credential(self.spec.cred_file, LarkCredential(
+            app_id=app_id, app_secret=app_secret,
+            bot_name=bot_name, bot_open_id=bot_open_id,
+            tenant_access_token=token, token_expires_at=token_expires_at,
+        ))
+        label = bot_name or app_id
+        return True, f"Lark connected: {label}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Lark credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Lark credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Lark: Not connected"
+        cred = load_credential(self.spec.cred_file, LarkCredential)
+        if not cred:
+            return True, "Lark: Connected\n  - app configured"
+        name = cred.bot_name or "Lark bot"
+        ident = cred.bot_open_id or cred.app_id or "app"
+        return True, f"Lark: Connected\n  - {name} ({ident})"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class LarkClient(BasePlatformClient):
+    spec = LARK
+    PLATFORM_ID = LARK.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[LarkCredential] = None
+        # WebSocket listener state. ``_ws_client`` is the lark_oapi.ws.Client
+        # instance; ``_ws_thread`` is the daemon thread it runs in (the SDK's
+        # ``start()`` is blocking so we can't await it). ``_dispatch_loop``
+        # captures the agent's asyncio loop at start_listening time so the
+        # synchronous WS-thread handler can ``run_coroutine_threadsafe`` back
+        # onto the right loop when forwarding messages to the agent.
+        self._ws_client: Optional[Any] = None
+        self._ws_thread: Optional[threading.Thread] = None
+        self._dispatch_loop: Optional[asyncio.AbstractEventLoop] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> LarkCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, LarkCredential)
+        if self._cred is None:
+            raise RuntimeError("No Lark credentials. Use /lark login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        return make_headers(self._load(), self.spec.cred_file)
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        # Default to open_id for the receive_id type - covers DM-to-user case.
+        # Callers that need group/email/user_id can use ``send_text`` directly.
+        receive_id_type = kwargs.get("receive_id_type", "open_id")
+        return self.send_text(recipient, text, receive_id_type=receive_id_type)
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    # ----- Listener (WebSocket via lark_oapi SDK) -----
+
+    async def start_listening(self, callback) -> None:
+        """Open a Long-Connection WebSocket to Lark and forward messages.
+
+        Uses ``lark_oapi.ws.Client`` which is the official SDK from ByteDance.
+        The SDK's ``start()`` is blocking + synchronous, so we run it on a
+        daemon thread and dispatch events back to the agent's asyncio loop
+        via ``run_coroutine_threadsafe``.
+
+        Auto-reconnect is enabled in the SDK - we don't need our own retry
+        loop. If the network drops, the SDK reconnects with backoff.
+        """
+        if self._listening:
+            return
+        try:
+            import lark_oapi as lark
+        except ImportError:
+            raise RuntimeError(
+                "lark-oapi not installed. Run: pip install lark-oapi"
+            )
+
+        cred = self._load()
+        self._message_callback = callback
+        self._dispatch_loop = asyncio.get_running_loop()
+
+        def _on_message(event: Any) -> None:
+            """Synchronous handler running on the SDK's WS thread."""
+            logger.info(f"[LARK] WS event received: {type(event).__name__}")
+            try:
+                msg = event.event.message
+                sender = event.event.sender
+            except AttributeError as e:
+                logger.warning(f"[LARK] unexpected event shape: {e}")
+                return
+            # Bounce back onto the agent's loop for the actual dispatch
+            loop = self._dispatch_loop
+            if loop and not loop.is_closed():
+                asyncio.run_coroutine_threadsafe(
+                    self._dispatch_message(msg, sender), loop,
+                )
+
+        handler = (
+            lark.EventDispatcherHandler.builder("", "")
+            .register_p2_im_message_receive_v1(_on_message)
+            .build()
+        )
+        self._ws_client = lark.ws.Client(
+            cred.app_id, cred.app_secret,
+            event_handler=handler,
+            domain="https://open.larksuite.com",
+            auto_reconnect=True,
+            log_level=lark.LogLevel.INFO,
+        )
+
+        def _run_ws() -> None:
+            try:
+                self._ws_client.start()
+            except Exception as e:
+                logger.error(f"[LARK] WS client crashed: {e}")
+
+        self._ws_thread = threading.Thread(
+            target=_run_ws, name="lark-ws", daemon=True,
+        )
+        self._ws_thread.start()
+        self._listening = True
+        logger.info("[LARK] Started WebSocket listener")
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        # The SDK doesn't expose a clean ``stop()`` - the WS thread is a
+        # daemon, so it dies when the agent process exits. For mid-run
+        # disconnect (logout) we drop our reference; the SDK's reconnect
+        # loop will keep running but no callback will fire (because
+        # ``_dispatch_loop`` is gone after this method).
+        self._ws_client = None
+        self._ws_thread = None
+        self._dispatch_loop = None
+        logger.info("[LARK] Stopped WebSocket listener")
+
+    async def _dispatch_message(self, msg: Any, sender: Any) -> None:
+        """Convert a Lark P2ImMessageReceiveV1 event into a PlatformMessage."""
+        if not self._listening or not self._message_callback:
+            return
+
+        # Skip messages sent by the bot itself (Lark echoes our sends back).
+        cred = self._cred
+        bot_open_id = cred.bot_open_id if cred else ""
+        sender_id = getattr(sender, "sender_id", None)
+        sender_open_id = getattr(sender_id, "open_id", "") if sender_id else ""
+        if bot_open_id and sender_open_id == bot_open_id:
+            return
+
+        # Lark message ``content`` is a JSON-encoded string. Text messages:
+        # ``{"text": "Hello"}``. Other types (post/image/file) we surface as
+        # the raw JSON for now - agent decides what to do with them.
+        msg_type = getattr(msg, "message_type", "") or ""
+        raw_content = getattr(msg, "content", "") or ""
+        text = ""
+        try:
+            parsed = json.loads(raw_content) if raw_content else {}
+            if msg_type == "text":
+                text = parsed.get("text", "")
+            else:
+                text = raw_content  # surface raw JSON for non-text types
+        except (json.JSONDecodeError, ValueError):
+            text = raw_content
+
+        if not text:
+            return
+
+        ts: Optional[datetime] = None
+        try:
+            create_time = getattr(msg, "create_time", None)
+            if create_time:
+                # Lark's create_time is millis since epoch as a string
+                ts = datetime.fromtimestamp(int(create_time) / 1000.0, tz=timezone.utc)
+        except (TypeError, ValueError):
+            pass
+
+        chat_id = getattr(msg, "chat_id", "") or ""
+        message_id = getattr(msg, "message_id", "") or ""
+        chat_type = getattr(msg, "chat_type", "") or ""
+
+        await self._message_callback(PlatformMessage(
+            platform=self.spec.platform_id,
+            sender_id=sender_open_id or "unknown",
+            sender_name=sender_open_id or "Lark user",
+            text=text,
+            channel_id=chat_id,
+            channel_name=f"Lark {chat_type}" if chat_type else "Lark",
+            message_id=message_id,
+            timestamp=ts,
+            raw={
+                "source": "Lark", "integrationType": "lark",
+                "is_self_message": False, "is_group": chat_type == "group",
+                "chat_id": chat_id, "chat_type": chat_type,
+                "message_type": msg_type, "raw_content": raw_content,
+            },
+        ))
+
+    # ----- REST methods -----
+
+    def send_text(self, receive_id: str, text: str,
+                  receive_id_type: str = "open_id") -> Result:
+        """Send a text message.
+
+        ``receive_id_type`` selects how Lark interprets ``receive_id``:
+          - ``open_id`` - a user's open_id (default, returned by user lookup)
+          - ``user_id`` - Lark's enterprise user_id
+          - ``email`` - the user's company email
+          - ``chat_id`` - a group chat id (oc_...)
+          - ``union_id`` - cross-app stable id
+
+        Lark's API quirk: the ``content`` field must be a JSON-encoded
+        STRING, not an object. Hence the literal ``\"`` escaping below.
+        """
+        import json as _json
+        payload = {
+            "receive_id": receive_id,
+            "msg_type": "text",
+            "content": _json.dumps({"text": text}, ensure_ascii=False),
+        }
+        return http_request(
+            "POST", f"{LARK_API_BASE}/im/v1/messages",
+            params={"receive_id_type": receive_id_type},
+            headers=self._headers(), json=payload, expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def reply_text(self, message_id: str, text: str) -> Result:
+        """Threaded reply to an existing message id (om_...)."""
+        import json as _json
+        return http_request(
+            "POST", f"{LARK_API_BASE}/im/v1/messages/{message_id}/reply",
+            headers=self._headers(),
+            json={"msg_type": "text", "content": _json.dumps({"text": text}, ensure_ascii=False)},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def get_user_by_email(self, email: str) -> Result:
+        """Resolve a user's open_id from a company email.
+
+        Uses Lark's batch-get endpoint with a single email; convenient
+        for "send a message to alice@company.com" workflows where the
+        caller doesn't know the open_id."""
+        return http_request(
+            "POST", f"{LARK_API_BASE}/contact/v3/users/batch_get_id",
+            params={"user_id_type": "open_id"},
+            headers=self._headers(), json={"emails": [email]}, expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def list_chats(self, page_size: int = 50) -> Result:
+        """List groups the bot is a member of."""
+        return http_request(
+            "GET", f"{LARK_API_BASE}/im/v1/chats",
+            params={"page_size": min(page_size, 100)},
+            headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def get_bot_info(self) -> Result:
+        """Connected bot's own profile (app_name, open_id, etc.)."""
+        return http_request(
+            "GET", f"{LARK_API_BASE}/bot/v3/info",
+            headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("bot", d),
+        )
diff --git a/craftos_integrations/integrations/lark_calendar/INTEGRATION.md b/craftos_integrations/integrations/lark_calendar/INTEGRATION.md
new file mode 100644
index 00000000..83d1c926
--- /dev/null
+++ b/craftos_integrations/integrations/lark_calendar/INTEGRATION.md
@@ -0,0 +1,14 @@
+# Lark Calendar — Integration Reference
+
+Lark Calendar via the same Custom App as `lark` and `lark_drive`. Events, free/busy, attendees, and auto-generated Lark Meetings.
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. Calendar changes are not pushed — request-response only.
+- **`calendar_id` defaults to `"primary"`** (the connected bot's own calendar). Don't ask for a calendar ID unless the user mentions a shared one — list via `list_lark_calendars` only when needed.
+- **Event and calendar IDs are opaque Lark strings.** Always discover via `list_lark_calendars` / `list_lark_calendar_events`; never construct.
+- **Times are Unix seconds (int).** The API wire format wraps them as `{"timestamp": "1730000000"}` (stringified) — the client does the conversion. The router just passes Unix seconds.
+- **Attendees are a separate call after `create_lark_calendar_event`.** Use `add_lark_event_attendees` afterward — `create_lark_calendar_event` does NOT accept attendees in its body. Attendees accept mixed types in one call: `user_ids` (Lark open_ids), `emails` (external), `chat_ids` (invites all group members).
+- **`with_video_meeting=True`** auto-attaches a Lark Meeting URL to the event.
+- **App-approval gotcha:** if the tenant admin hasn't approved the Custom App, the endpoints often still answer 200 but no events sync. If the user reports "the agent doesn't see my Lark calendar," tell them to check admin approval before retrying.
+- **Same Custom App as `lark` / `lark_drive`** — App ID + Secret are pasted into each service separately (independent connect/disconnect tiles).
diff --git a/craftos_integrations/integrations/lark_calendar/__init__.py b/craftos_integrations/integrations/lark_calendar/__init__.py
new file mode 100644
index 00000000..aeaf8dd4
--- /dev/null
+++ b/craftos_integrations/integrations/lark_calendar/__init__.py
@@ -0,0 +1,326 @@
+# -*- coding: utf-8 -*-
+"""Lark Calendar integration - events, scheduling, free/busy.
+
+Same Custom App as ``lark.py`` (messaging) and ``lark_drive.py`` - App ID +
+Secret + tenant_access_token - but registered as a sibling integration with
+its own credential file (``lark_calendar.json``) so it shows as an
+independent tile in the UI. Permissions are gated separately per service.
+
+API quirk worth knowing: Lark's Calendar API expects Unix timestamps as
+**strings** inside ``{"timestamp": "1730000000"}`` objects. The client
+methods accept ``int`` and stringify internally so callers don't have to
+think about it.
+
+Required Lark permissions (Permissions & Scopes tab on the Custom App):
+  - ``calendar:calendar`` (full read-write) OR
+    ``calendar:calendar:readonly`` (read-only)
+  - For events with attendees: ``calendar:calendar.event.attendee``
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._lark_common import (
+    LARK_API_BASE,
+    LarkCredential,
+    make_headers,
+    validate_and_mint_token,
+)
+
+logger = get_logger(__name__)
+
+
+LARK_CALENDAR = IntegrationSpec(
+    name="lark_calendar",
+    cred_class=LarkCredential,
+    cred_file="lark_calendar.json",
+    platform_id="lark_calendar",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(LARK_CALENDAR.name)
+class LarkCalendarHandler(IntegrationHandler):
+    spec = LARK_CALENDAR
+    display_name = "Lark Calendar"
+    description = "Events, scheduling, and free/busy on Lark Calendar"
+    auth_type = "token"
+    icon = "lark"
+    connect_help = [
+        "Use the same Custom App you created for /lark (or create one at open.larksuite.com/app)",
+        "Permissions & Scopes → enable: calendar:calendar (read-write) and calendar:calendar.event.attendee (for invites)",
+        "Version Management → Create Version → submit for tenant admin approval - required for new scopes to take effect",
+        "Credentials & Basic Info → copy App ID + App Secret and paste them below (same values as /lark)",
+    ]
+    fields = [
+        {"key": "app_id", "label": "App ID",
+         "placeholder": "cli_xxxxxxxxxx", "password": False},
+        {"key": "app_secret", "label": "App Secret",
+         "placeholder": "From Credentials & Basic Info tab", "password": True},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 2:
+            return False, ("Usage: /lark_calendar login <app_id> <app_secret>\n"
+                           "Use the same App ID + Secret as /lark; just make sure calendar:* "
+                           "scopes are enabled on the same Custom App.")
+        app_id, app_secret = args[0], args[1]
+        token, token_expires_at, err = validate_and_mint_token(app_id, app_secret)
+        if err:
+            return False, err
+
+        save_credential(self.spec.cred_file, LarkCredential(
+            app_id=app_id, app_secret=app_secret,
+            tenant_access_token=token, token_expires_at=token_expires_at,
+        ))
+        return True, f"Lark Calendar connected: {app_id}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Lark Calendar credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Lark Calendar credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Lark Calendar: Not connected"
+        cred = load_credential(self.spec.cred_file, LarkCredential)
+        if not cred:
+            return True, "Lark Calendar: Connected\n  - app configured"
+        return True, f"Lark Calendar: Connected\n  - {cred.app_id}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class LarkCalendarClient(BasePlatformClient):
+    spec = LARK_CALENDAR
+    PLATFORM_ID = LARK_CALENDAR.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[LarkCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> LarkCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, LarkCredential)
+        if self._cred is None:
+            raise RuntimeError("No Lark Calendar credentials. Use /lark_calendar login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        return make_headers(self._load(), self.spec.cred_file)
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "Lark Calendar does not support send_message - use create_event"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- Calendars -----
+
+    def list_calendars(self, page_size: int = 20, page_token: str = "") -> Result:
+        """List the bot's accessible calendars (its own + any shared with it)."""
+        params: Dict[str, str] = {"page_size": str(min(page_size, 1000))}
+        if page_token:
+            params["page_token"] = page_token
+        return http_request(
+            "GET", f"{LARK_API_BASE}/calendar/v4/calendars",
+            params=params, headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def get_primary_calendar(self) -> Result:
+        """Get the bot's primary calendar (the one it owns by default)."""
+        return http_request(
+            "POST", f"{LARK_API_BASE}/calendar/v4/calendars/primary",
+            headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    # ----- Events -----
+
+    def list_events(self, calendar_id: str, start_time: int, end_time: int,
+                    page_size: int = 50, page_token: str = "") -> Result:
+        """List events in a date range. Times are Unix seconds (int)."""
+        params: Dict[str, str] = {
+            "start_time": str(start_time),
+            "end_time": str(end_time),
+            "page_size": str(min(page_size, 1000)),
+        }
+        if page_token:
+            params["page_token"] = page_token
+        return http_request(
+            "GET", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events",
+            params=params, headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def get_event(self, calendar_id: str, event_id: str) -> Result:
+        return http_request(
+            "GET", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events/{event_id}",
+            headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def create_event(self, calendar_id: str, summary: str,
+                     start_time: int, end_time: int,
+                     description: str = "",
+                     location: str = "",
+                     with_video_meeting: bool = False) -> Result:
+        """Create an event. Times are Unix seconds (int).
+
+        ``with_video_meeting=True`` asks Lark to auto-generate a Lark Meeting
+        URL and attach it. Attendees are added separately via
+        ``add_event_attendees`` after creation - Lark's create endpoint
+        doesn't accept attendees in the same body.
+        """
+        body: Dict[str, Any] = {
+            "summary": summary,
+            "start_time": {"timestamp": str(start_time)},
+            "end_time": {"timestamp": str(end_time)},
+        }
+        if description:
+            body["description"] = description
+        if location:
+            body["location"] = {"name": location}
+        if with_video_meeting:
+            body["vchat"] = {"vc_type": "vc"}
+        return http_request(
+            "POST", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events",
+            headers=self._headers(), json=body, expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def update_event(self, calendar_id: str, event_id: str,
+                     summary: Optional[str] = None,
+                     description: Optional[str] = None,
+                     start_time: Optional[int] = None,
+                     end_time: Optional[int] = None,
+                     location: Optional[str] = None) -> Result:
+        """Patch an event. Only fields with non-None values are sent."""
+        body: Dict[str, Any] = {}
+        if summary is not None:
+            body["summary"] = summary
+        if description is not None:
+            body["description"] = description
+        if start_time is not None:
+            body["start_time"] = {"timestamp": str(start_time)}
+        if end_time is not None:
+            body["end_time"] = {"timestamp": str(end_time)}
+        if location is not None:
+            body["location"] = {"name": location}
+        if not body:
+            return {"error": "No fields provided to update"}
+        return http_request(
+            "PATCH", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events/{event_id}",
+            headers=self._headers(), json=body, expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def delete_event(self, calendar_id: str, event_id: str,
+                     need_notification: bool = True) -> Result:
+        """Delete an event. ``need_notification`` controls whether attendees
+        are emailed about the cancellation."""
+        params = {"need_notification": "true" if need_notification else "false"}
+        return http_request(
+            "DELETE", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events/{event_id}",
+            params=params, headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def search_events(self, calendar_id: str, query: str,
+                      start_time: Optional[int] = None,
+                      end_time: Optional[int] = None,
+                      page_size: int = 20) -> Result:
+        """Full-text search over event summary/description in one calendar."""
+        body: Dict[str, Any] = {"query": query}
+        if start_time is not None and end_time is not None:
+            body["filter"] = {
+                "start_time": {"timestamp": str(start_time)},
+                "end_time": {"timestamp": str(end_time)},
+            }
+        return http_request(
+            "POST", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events/search",
+            params={"page_size": str(min(page_size, 100))},
+            headers=self._headers(), json=body, expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    # ----- Attendees -----
+
+    def add_event_attendees(self, calendar_id: str, event_id: str,
+                            user_ids: Optional[List[str]] = None,
+                            emails: Optional[List[str]] = None,
+                            chat_ids: Optional[List[str]] = None,
+                            need_notification: bool = True) -> Result:
+        """Invite attendees to an event.
+
+        Pass any combination of ``user_ids`` (Lark open_ids), ``emails``
+        (external attendees), and ``chat_ids`` (group chats - every member
+        gets invited). Lark's API normalizes these into a single
+        ``attendees`` list with per-entry ``type``.
+        """
+        attendees: List[Dict[str, str]] = []
+        for uid in (user_ids or []):
+            attendees.append({"type": "user", "user_id": uid})
+        for em in (emails or []):
+            attendees.append({"type": "third_party", "third_party_email": em})
+        for cid in (chat_ids or []):
+            attendees.append({"type": "chat", "chat_id": cid})
+        if not attendees:
+            return {"error": "No attendees provided"}
+        return http_request(
+            "POST", f"{LARK_API_BASE}/calendar/v4/calendars/{calendar_id}/events/{event_id}/attendees",
+            headers=self._headers(),
+            json={"attendees": attendees, "need_notification": need_notification},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    # ----- Free/busy -----
+
+    def check_free_busy(self, user_ids: List[str],
+                        start_time: int, end_time: int) -> Result:
+        """Bulk free/busy query for a list of users over a time window.
+
+        Returns each user's busy intervals in the window - useful for
+        finding a meeting slot that works for everyone.
+        """
+        return http_request(
+            "POST", f"{LARK_API_BASE}/calendar/v4/freebusy/list",
+            headers=self._headers(),
+            json={
+                "time_min": {"timestamp": str(start_time)},
+                "time_max": {"timestamp": str(end_time)},
+                "user_id_list": user_ids,
+            },
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
diff --git a/craftos_integrations/integrations/lark_drive/INTEGRATION.md b/craftos_integrations/integrations/lark_drive/INTEGRATION.md
new file mode 100644
index 00000000..02c21811
--- /dev/null
+++ b/craftos_integrations/integrations/lark_drive/INTEGRATION.md
@@ -0,0 +1,13 @@
+# Lark Drive — Integration Reference
+
+Files and folders in Lark Drive via the same Custom App as `lark` and `lark_calendar`. Backs Lark Docs, Sheets, and Bitable internally.
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. File-change events are not pushed — request-response only.
+- **`folder_token` empty string = the user's Drive root.** No "/" path — pass `""` to list root.
+- **All identifiers are opaque tokens, not paths.** `file_token` and `folder_token` are Lark-generated strings; there are no human-readable paths. Always `list_lark_drive_files` or `search_lark_drive_files` to resolve names → tokens before any operation.
+- **`delete_lark_drive_file` requires the correct `file_type`.** Values: `file`, `folder`, `doc`, `docx`, `sheet`, `bitable`, `mindnote`, `shortcut`, `slides`. Mismatched type silently fails — get the type from `get_lark_drive_file_metadata` first if unsure.
+- **Pagination:** pass returned `next_page_token` back until `has_more` is false. The router shouldn't assume the first page is the full list.
+- **Upload cap is 20MB.** Larger files would need chunked upload, which the integration does NOT yet implement. Tell the user up-front rather than retrying after a failure.
+- **Same Custom App as `lark` / `lark_calendar`** — App ID + Secret are pasted into each service separately (independent connect/disconnect tiles).
diff --git a/craftos_integrations/integrations/lark_drive/__init__.py b/craftos_integrations/integrations/lark_drive/__init__.py
new file mode 100644
index 00000000..9b083171
--- /dev/null
+++ b/craftos_integrations/integrations/lark_drive/__init__.py
@@ -0,0 +1,285 @@
+# -*- coding: utf-8 -*-
+"""Lark Drive integration - list/upload/download/move files in Lark Drive.
+
+Lark Drive is the file-storage layer of the Lark workspace; it backs Lark
+Docs, Sheets, Bitable, etc. (those services reference Drive ``file_token``
+identifiers internally) but for this integration "Drive" means the user-
+visible files-and-folders surface only.
+
+Auth is the same Custom App that messaging uses - App ID + Secret minting a
+``tenant_access_token`` - but each Lark service is registered as its own
+sibling integration (matches the ``google_*.py`` pattern). The user pastes
+the same App ID + Secret here as in ``/lark login``; the only effective
+difference is the cred file (``lark_drive.json`` vs ``lark.json``) and the
+permissions enabled on the app.
+
+Required Lark permissions (Permissions & Scopes tab on the Custom App):
+  - ``drive:drive`` (full read-write) OR ``drive:drive:readonly`` (read-only)
+  - ``drive:file:upload`` (only if you want to upload via this integration)
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+from .._lark_common import (
+    LARK_API_BASE,
+    LarkCredential,
+    ensure_token,
+    make_headers,
+    validate_and_mint_token,
+)
+
+logger = get_logger(__name__)
+
+
+LARK_DRIVE = IntegrationSpec(
+    name="lark_drive",
+    cred_class=LarkCredential,
+    cred_file="lark_drive.json",
+    platform_id="lark_drive",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(LARK_DRIVE.name)
+class LarkDriveHandler(IntegrationHandler):
+    spec = LARK_DRIVE
+    display_name = "Lark Drive"
+    description = "Files and folders in Lark Drive"
+    auth_type = "token"
+    icon = "lark"
+    connect_help = [
+        "Use the same Custom App you created for /lark (or create one at open.larksuite.com/app)",
+        "Permissions & Scopes → enable: drive:drive (read-write) and drive:file:upload",
+        "Version Management → Create Version → submit for tenant admin approval - required for the new scopes to take effect",
+        "Credentials & Basic Info → copy App ID + App Secret and paste them below (same values as /lark)",
+    ]
+    fields = [
+        {"key": "app_id", "label": "App ID",
+         "placeholder": "cli_xxxxxxxxxx", "password": False},
+        {"key": "app_secret", "label": "App Secret",
+         "placeholder": "From Credentials & Basic Info tab", "password": True},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 2:
+            return False, ("Usage: /lark_drive login <app_id> <app_secret>\n"
+                           "Use the same App ID + Secret as /lark; just make sure drive:* "
+                           "scopes are enabled on the same Custom App.")
+        app_id, app_secret = args[0], args[1]
+        token, token_expires_at, err = validate_and_mint_token(app_id, app_secret)
+        if err:
+            return False, err
+
+        save_credential(self.spec.cred_file, LarkCredential(
+            app_id=app_id, app_secret=app_secret,
+            tenant_access_token=token, token_expires_at=token_expires_at,
+        ))
+        return True, f"Lark Drive connected: {app_id}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Lark Drive credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Lark Drive credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Lark Drive: Not connected"
+        cred = load_credential(self.spec.cred_file, LarkCredential)
+        if not cred:
+            return True, "Lark Drive: Connected\n  - app configured"
+        return True, f"Lark Drive: Connected\n  - {cred.app_id}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class LarkDriveClient(BasePlatformClient):
+    spec = LARK_DRIVE
+    PLATFORM_ID = LARK_DRIVE.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[LarkCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> LarkCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, LarkCredential)
+        if self._cred is None:
+            raise RuntimeError("No Lark Drive credentials. Use /lark_drive login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        return make_headers(self._load(), self.spec.cred_file)
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return {"error": "Lark Drive does not support send_message"}
+
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def list_files(self, folder_token: str = "", page_size: int = 50,
+                   page_token: str = "") -> Result:
+        """List files in a folder. Empty ``folder_token`` lists the root.
+
+        Pagination: pass the returned ``next_page_token`` back as ``page_token``
+        until ``has_more`` is False.
+        """
+        params: Dict[str, str] = {"page_size": str(min(page_size, 200))}
+        if folder_token:
+            params["folder_token"] = folder_token
+        if page_token:
+            params["page_token"] = page_token
+        return http_request(
+            "GET", f"{LARK_API_BASE}/drive/v1/files",
+            params=params, headers=self._headers(), expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def get_file_metadata(self, file_tokens: List[str],
+                          doc_type: str = "file") -> Result:
+        """Batch-fetch metadata for one or more file tokens.
+
+        ``doc_type`` is one of: ``doc`` (legacy Doc), ``docx`` (new Doc),
+        ``sheet``, ``bitable``, ``mindnote``, ``file`` (regular file),
+        ``slides``. Mixed-type batches are allowed by passing a list of
+        ``{doc_token, doc_type}`` pairs via ``request_docs`` directly to
+        the API instead of going through this convenience method.
+        """
+        return http_request(
+            "POST", f"{LARK_API_BASE}/drive/v1/metas/batch_query",
+            headers=self._headers(),
+            json={"request_docs": [
+                {"doc_token": t, "doc_type": doc_type} for t in file_tokens
+            ]},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def create_folder(self, name: str, parent_folder_token: str = "") -> Result:
+        """Create a new folder. Empty ``parent_folder_token`` creates at the root."""
+        return http_request(
+            "POST", f"{LARK_API_BASE}/drive/v1/files/create_folder",
+            headers=self._headers(),
+            json={"name": name, "folder_token": parent_folder_token},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def upload_file(self, file_path: str, parent_folder_token: str,
+                    file_name: str = "") -> Result:
+        """Upload a file (max 20MB) to a folder.
+
+        Lark's upload_all endpoint is multipart/form-data with the file size
+        as a form field - the SDK quirk is the size has to be a string. For
+        files >20MB the API requires the chunked upload_prepare/upload_part/
+        upload_finish flow, which this method does NOT handle.
+        """
+        import os
+        if not file_name:
+            file_name = os.path.basename(file_path)
+        size = os.path.getsize(file_path)
+        if size > 20 * 1024 * 1024:
+            return {"error": f"File too large ({size} bytes). Use chunked "
+                             "upload for files >20MB (not yet implemented)."}
+        with open(file_path, "rb") as f:
+            file_data = f.read()
+        # Multipart form: file_name, parent_type=explorer, parent_node, size, file
+        # The token bearer is added via Authorization header; Content-Type is
+        # set by the multipart encoder, NOT our default JSON.
+        token = ensure_token(self._load(), self.spec.cred_file)
+        return http_request(
+            "POST", f"{LARK_API_BASE}/drive/v1/files/upload_all",
+            headers={"Authorization": f"Bearer {token}"},
+            data={
+                "file_name": file_name,
+                "parent_type": "explorer",
+                "parent_node": parent_folder_token,
+                "size": str(size),
+            },
+            files={"file": (file_name, file_data)},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def download_file(self, file_token: str, dest_path: str) -> Result:
+        """Download a file by its token to ``dest_path`` on disk.
+
+        Returns ``{ok, result: {path, bytes_written}}`` on success.
+        """
+        token = ensure_token(self._load(), self.spec.cred_file)
+        # http_request returns parsed JSON - for a binary download we use
+        # transform=None and read the raw bytes off the response. Easier
+        # path: do a raw httpx call here to avoid teaching the helper
+        # about binary responses.
+        import httpx
+        try:
+            with httpx.stream(
+                "GET", f"{LARK_API_BASE}/drive/v1/files/{file_token}/download",
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=60.0,
+            ) as resp:
+                if resp.status_code != 200:
+                    return {"error": f"Download failed: HTTP {resp.status_code}",
+                            "details": resp.read().decode("utf-8", errors="replace")[:500]}
+                bytes_written = 0
+                with open(dest_path, "wb") as f:
+                    for chunk in resp.iter_bytes(chunk_size=64 * 1024):
+                        f.write(chunk)
+                        bytes_written += len(chunk)
+                return {"ok": True, "result": {"path": dest_path,
+                                                "bytes_written": bytes_written}}
+        except (httpx.HTTPError, OSError) as e:
+            return {"error": f"Download failed: {e}"}
+
+    def delete_file(self, file_token: str, file_type: str = "file") -> Result:
+        """Delete a file or folder by token.
+
+        ``file_type`` is one of: ``file``, ``folder``, ``doc``, ``docx``,
+        ``sheet``, ``bitable``, ``mindnote``, ``shortcut``, ``slides``.
+        """
+        return http_request(
+            "DELETE", f"{LARK_API_BASE}/drive/v1/files/{file_token}",
+            params={"type": file_type}, headers=self._headers(),
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
+
+    def search_files(self, search_key: str, count: int = 20) -> Result:
+        """Full-text search across files the bot has access to."""
+        return http_request(
+            "POST", f"{LARK_API_BASE}/drive/v2/files/search_app",
+            headers=self._headers(),
+            json={"search_key": search_key, "count": min(count, 50)},
+            expected=(200,),
+            transform=lambda d: d.get("data", d),
+        )
diff --git a/craftos_integrations/integrations/line/INTEGRATION.md b/craftos_integrations/integrations/line/INTEGRATION.md
new file mode 100644
index 00000000..16f316ee
--- /dev/null
+++ b/craftos_integrations/integrations/line/INTEGRATION.md
@@ -0,0 +1,12 @@
+# LINE — Integration Reference
+
+LINE Messaging API integration. Send-only — incoming messages arrive via webhook configured outside this integration.
+
+## Essentials
+
+- **No incoming-message listener.** This is SEND-only — the agent can push, multicast, broadcast, or reply (via reply token from a webhook event). Direct messages from users do NOT arrive through any agent poll. If a user expects the agent to react to their LINE messages, that requires the webhook to be configured on the LINE Developer console.
+- **Identity format:** LINE IDs are prefix-coded — `U...` = user, `C...` = group, `R...` = room. No `@username` or search endpoint — the agent must already have the ID.
+- **Reply tokens are single-use and short-lived.** Use `reply_line_message` only against a token from an incoming webhook event; do NOT cache or reuse. After the token expires (or is consumed), fall back to `send_line_message` (push) — which counts against monthly quota.
+- **Session-level facts the integration knows:** `bot_user_id`, `bot_display_name`. Use `get_line_bot_info`.
+- **Push quotas:** push/multicast/broadcast count against the monthly message quota. Check remaining quota via `get_line_quota` before bulk sends; surface a clear error if exhausted instead of failing each send.
+- **Config knobs:** `notification_disabled` silences push alerts; `message_prefix` prepends a string to every outgoing text.
diff --git a/craftos_integrations/integrations/line/__init__.py b/craftos_integrations/integrations/line/__init__.py
new file mode 100644
index 00000000..fb4bb59e
--- /dev/null
+++ b/craftos_integrations/integrations/line/__init__.py
@@ -0,0 +1,291 @@
+# -*- coding: utf-8 -*-
+"""LINE Messaging API integration.
+
+LINE delivers inbound messages via webhooks only - there is no long-poll
+endpoint. The bot needs a public HTTPS URL registered in the LINE
+Developers console to receive messages, which a desktop agent cannot
+provide directly. This integration is therefore **send-only** out of the
+box: ``send_message`` (push) and ``reply_message`` work; ``start_listening``
+is not supported.
+
+Credentials come from the LINE Developers console
+(https://developers.line.biz/console/) under your provider → Messaging
+API channel:
+    - Channel access token (long-lived) - for the Authorization header.
+    - Channel secret - used to verify webhook signatures (stored for
+      future webhook-server use; not required for send-only).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    has_credential,
+    load_config,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+LINE_API_BASE = "https://api.line.me/v2/bot"
+
+
+@dataclass
+class LineCredential:
+    channel_access_token: str = ""
+    channel_secret: str = ""
+    bot_user_id: str = ""
+    bot_display_name: str = ""
+
+
+@dataclass
+class LineConfig:
+    """Runtime knobs persisted to ``line_config.json``."""
+    # When True, every outgoing push/multicast/broadcast is sent with
+    # ``notificationDisabled: true`` - recipients receive the message but
+    # no push alert. Useful for bulk/automated sends that shouldn't wake
+    # users up.
+    notification_disabled: bool = False
+    # Optional prefix prepended to every outgoing text message (e.g.
+    # ``"[CraftBot] "``). Empty means no prefix. Helps recipients
+    # distinguish bot-generated messages from human ones.
+    message_prefix: str = ""
+
+
+LINE = IntegrationSpec(
+    name="line",
+    cred_class=LineCredential,
+    cred_file="line.json",
+    platform_id="line",
+)
+
+
+def _line_config_file() -> str:
+    """``line.json`` → ``line_config.json``."""
+    stem = LINE.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(LINE.name)
+class LineHandler(IntegrationHandler):
+    spec = LINE
+    display_name = "LINE Business"
+    description = "Messaging via LINE Messaging API (send-only)"
+    auth_type = "token"
+    icon = "line"
+    connect_help = [
+        "Open LINE Developers Console: developers.line.biz/console",
+        "Sign in with your LINE account",
+        "Create a Provider, then create a Messaging API channel inside it",
+        "Channel Secret → Basic settings tab → 'Channel secret' field",
+        "Channel Access Token → Messaging API tab → 'Issue' button under 'Channel access token (long-lived)'",
+    ]
+    fields = [
+        {"key": "channel_access_token", "label": "Channel Access Token",
+         "placeholder": "Long-lived token from LINE Developers console", "password": True},
+        {"key": "channel_secret", "label": "Channel Secret",
+         "placeholder": "From the same Messaging API channel", "password": True, "optional": True},
+    ]
+
+    config_class = LineConfig
+    config_fields = [
+        {"key": "notification_disabled", "label": "Silent delivery", "type": "checkbox",
+         "help": "Send all push/multicast/broadcast messages with notificationDisabled=true. "
+                 "Recipients receive the message but get no push alert."},
+        {"key": "message_prefix", "label": "Message prefix", "type": "text",
+         "placeholder": "[CraftBot] ",
+         "help": "Optional prefix prepended to every outgoing text message. Leave empty for none."},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, ("Usage: /line login <channel_access_token> [channel_secret]\n"
+                           "Get from https://developers.line.biz/console/ → "
+                           "Messaging API channel → Channel access token (long-lived).")
+        token = args[0]
+        secret = args[1] if len(args) > 1 else ""
+
+        result = http_request(
+            "GET", f"{LINE_API_BASE}/info",
+            headers={"Authorization": f"Bearer {token}"},
+            expected=(200,),
+        )
+        if "error" in result:
+            return False, f"Invalid channel access token: {result['error']}"
+        info = result.get("result", {})
+
+        save_credential(self.spec.cred_file, LineCredential(
+            channel_access_token=token,
+            channel_secret=secret,
+            bot_user_id=info.get("userId", ""),
+            bot_display_name=info.get("displayName", ""),
+        ))
+        label = info.get("displayName") or info.get("userId") or "bot"
+        return True, f"LINE connected: {label}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No LINE credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed LINE credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "LINE: Not connected"
+        cred = load_credential(self.spec.cred_file, LineCredential)
+        if not cred:
+            return True, "LINE: Connected\n  - bot configured"
+        name = cred.bot_display_name or "LINE bot"
+        ident = cred.bot_user_id or "bot configured"
+        return True, f"LINE: Connected\n  - {name} ({ident})"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class LineClient(BasePlatformClient):
+    spec = LINE
+    PLATFORM_ID = LINE.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[LineCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> LineCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, LineCredential)
+        if self._cred is None:
+            raise RuntimeError("No LINE credentials. Use /line login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        return {"Authorization": f"Bearer {cred.channel_access_token}",
+                "Content-Type": "application/json"}
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return self.push_text(recipient, text)
+
+    # LINE delivers inbound messages via webhook only; no long-poll
+    # equivalent exists. Listening is intentionally not implemented.
+    @property
+    def supports_listening(self) -> bool:
+        return False
+
+    # ----- REST methods -----
+
+    def _config(self) -> LineConfig:
+        return load_config(_line_config_file(), LineConfig) or LineConfig()
+
+    def _shape_text(self, text: str) -> str:
+        prefix = self._config().message_prefix
+        return f"{prefix}{text}" if prefix else text
+
+    def push_text(self, to: str, text: str) -> Result:
+        """Send a text message to a user/group/room ID via the push endpoint."""
+        cfg = self._config()
+        payload: Dict[str, Any] = {
+            "to": to,
+            "messages": [{"type": "text", "text": self._shape_text(text)}],
+        }
+        if cfg.notification_disabled:
+            payload["notificationDisabled"] = True
+        return http_request(
+            "POST", f"{LINE_API_BASE}/message/push",
+            headers=self._headers(), json=payload, expected=(200,),
+        )
+
+    def reply_text(self, reply_token: str, text: str) -> Result:
+        """Reply within the 1-minute window using a reply token from the webhook payload."""
+        cfg = self._config()
+        payload: Dict[str, Any] = {
+            "replyToken": reply_token,
+            "messages": [{"type": "text", "text": self._shape_text(text)}],
+        }
+        if cfg.notification_disabled:
+            payload["notificationDisabled"] = True
+        return http_request(
+            "POST", f"{LINE_API_BASE}/message/reply",
+            headers=self._headers(), json=payload, expected=(200,),
+        )
+
+    def multicast_text(self, to: List[str], text: str) -> Result:
+        """Send the same message to up to 500 user IDs in one call."""
+        cfg = self._config()
+        payload: Dict[str, Any] = {
+            "to": to,
+            "messages": [{"type": "text", "text": self._shape_text(text)}],
+        }
+        if cfg.notification_disabled:
+            payload["notificationDisabled"] = True
+        return http_request(
+            "POST", f"{LINE_API_BASE}/message/multicast",
+            headers=self._headers(), json=payload, expected=(200,),
+        )
+
+    def broadcast_text(self, text: str) -> Result:
+        """Send a message to every user that has the bot as a friend."""
+        cfg = self._config()
+        payload: Dict[str, Any] = {
+            "messages": [{"type": "text", "text": self._shape_text(text)}],
+        }
+        if cfg.notification_disabled:
+            payload["notificationDisabled"] = True
+        return http_request(
+            "POST", f"{LINE_API_BASE}/message/broadcast",
+            headers=self._headers(), json=payload, expected=(200,),
+        )
+
+    def get_profile(self, user_id: str) -> Result:
+        """Fetch a user's display name / picture URL by their LINE user ID."""
+        return http_request(
+            "GET", f"{LINE_API_BASE}/profile/{user_id}",
+            headers={"Authorization": f"Bearer {self._load().channel_access_token}"},
+            expected=(200,),
+        )
+
+    def get_bot_info(self) -> Result:
+        """Fetch the connected bot's own profile (userId, displayName, picture)."""
+        return http_request(
+            "GET", f"{LINE_API_BASE}/info",
+            headers={"Authorization": f"Bearer {self._load().channel_access_token}"},
+            expected=(200,),
+        )
+
+    def get_quota(self) -> Result:
+        """Return the bot's monthly push-message quota."""
+        return http_request(
+            "GET", f"{LINE_API_BASE}/message/quota",
+            headers={"Authorization": f"Bearer {self._load().channel_access_token}"},
+            expected=(200,),
+        )
diff --git a/craftos_integrations/integrations/linkedin/INTEGRATION.md b/craftos_integrations/integrations/linkedin/INTEGRATION.md
new file mode 100644
index 00000000..65f85cb1
--- /dev/null
+++ b/craftos_integrations/integrations/linkedin/INTEGRATION.md
@@ -0,0 +1,12 @@
+# LinkedIn — Integration Reference
+
+Official LinkedIn API integration. Profile, posts, search, organisation analytics, and (with elevated perms) DMs.
+
+## Essentials
+
+- **Recipient is a LinkedIn URN, not a username or numeric ID.** Format: `urn:li:person:<linkedin_id>`. The integration handles URL-encoding internally — pass the raw URN string verbatim.
+- **The integration knows the user's own `linkedin_id`** (the `sub` claim from the OAuth userinfo response). NEVER ask the user for it; the integration auto-constructs `urn:li:person:<linkedin_id>` for self-references.
+- **Many endpoints need elevated API access.** Search-people, search-jobs, and messaging often return a `"note"` field warning that LinkedIn restricts access to non-partner apps. Surface that note to the user — they likely need a different API tier; retrying won't help.
+- **Posts have a 3000-character limit.** Truncate or split before calling `create_linkedin_post`; don't let LinkedIn truncate silently.
+- **Access tokens last ~60 days** with automatic refresh. A 401 usually means revocation (the user disconnected the app), not expiry — direct them to reconnect.
+- **URN identity zoo:** `urn:li:person:...` for users, `urn:li:organization:...` for companies, `urn:li:share:...` for posts. They're not interchangeable — read each action's schema for which it expects.
diff --git a/craftos_integrations/integrations/linkedin/__init__.py b/craftos_integrations/integrations/linkedin/__init__.py
new file mode 100644
index 00000000..395ed619
--- /dev/null
+++ b/craftos_integrations/integrations/linkedin/__init__.py
@@ -0,0 +1,561 @@
+# -*- coding: utf-8 -*-
+"""LinkedIn integration - handler (OAuth) + client."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import quote
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    OAuthFlow,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...config import ConfigStore
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+LINKEDIN_API_BASE = "https://api.linkedin.com/v2"
+LINKEDIN_OAUTH_BASE = "https://www.linkedin.com/oauth/v2"
+
+
+@dataclass
+class LinkedInCredential:
+    access_token: str = ""
+    refresh_token: str = ""
+    token_expiry: float = 0.0
+    client_id: str = ""
+    client_secret: str = ""
+    linkedin_id: str = ""
+    user_id: str = ""
+
+
+LINKEDIN = IntegrationSpec(
+    name="linkedin",
+    cred_class=LinkedInCredential,
+    cred_file="linkedin.json",
+    platform_id="linkedin",
+)
+
+
+def _encode_urn(urn: str) -> str:
+    return quote(urn, safe="")
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(LINKEDIN.name)
+class LinkedInHandler(IntegrationHandler):
+    spec = LINKEDIN
+    display_name = "LinkedIn"
+    description = "Professional network"
+    auth_type = "oauth"
+    icon = "linkedin"
+    connect_help = [
+        "Click 'Sign in with LinkedIn' below",
+        "A browser tab will open at linkedin.com/oauth - sign in with your LinkedIn account",
+        "Approve the requested permissions (read profile, post on behalf, etc.)",
+        "You'll be redirected back to CraftBot once consent completes",
+    ]
+    fields: List = []
+
+    oauth = OAuthFlow(
+        client_id_key="LINKEDIN_CLIENT_ID",
+        client_secret_key="LINKEDIN_CLIENT_SECRET",
+        auth_url="https://www.linkedin.com/oauth/v2/authorization",
+        token_url="https://www.linkedin.com/oauth/v2/accessToken",
+        userinfo_url="https://api.linkedin.com/v2/userinfo",
+        scopes="openid profile email w_member_social",
+    )
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        result = await self.oauth.run()
+        if "error" in result and not result.get("access_token"):
+            return False, f"LinkedIn OAuth failed: {result['error']}"
+
+        info = result.get("userinfo", {})
+        save_credential(self.spec.cred_file, LinkedInCredential(
+            access_token=result["access_token"],
+            refresh_token=result.get("refresh_token", ""),
+            token_expiry=time.time() + result.get("expires_in", 3600),
+            client_id=ConfigStore.get_oauth("LINKEDIN_CLIENT_ID"),
+            client_secret=ConfigStore.get_oauth("LINKEDIN_CLIENT_SECRET"),
+            linkedin_id=info.get("sub", ""),
+            user_id=info.get("sub", ""),
+        ))
+        return True, f"LinkedIn connected as {info.get('name')} ({info.get('email')})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No LinkedIn credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed LinkedIn credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "LinkedIn: Not connected"
+        cred = load_credential(self.spec.cred_file, LinkedInCredential)
+        lid = cred.linkedin_id if cred else "unknown"
+        return True, f"LinkedIn: Connected\n  - {lid}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class LinkedInClient(BasePlatformClient):
+    spec = LINKEDIN
+    PLATFORM_ID = LINKEDIN.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[LinkedInCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> LinkedInCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, LinkedInCredential)
+        if self._cred is None:
+            raise RuntimeError("No LinkedIn credentials. Use /linkedin login first.")
+        return self._cred
+
+    def _ensure_token(self) -> str:
+        cred = self._load()
+        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
+            result = self.refresh_access_token()
+            if result:
+                return result
+        return cred.access_token
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._ensure_token()}",
+            "Content-Type": "application/json",
+            "X-Restli-Protocol-Version": "2.0.0",
+            "LinkedIn-Version": "202401",
+        }
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        cred = self._load()
+        sender_urn = f"urn:li:person:{cred.linkedin_id}" if cred.linkedin_id else ""
+        return self.send_message_to_recipients(
+            sender_urn=sender_urn, recipient_urns=[recipient],
+            subject=kwargs.get("subject", ""), body=text,
+        )
+
+    def refresh_access_token(self) -> Optional[str]:
+        cred = self._load()
+        if not all([cred.client_id, cred.client_secret, cred.refresh_token]):
+            return None
+        result = http_request("POST", f"{LINKEDIN_OAUTH_BASE}/accessToken", data={
+            "grant_type": "refresh_token",
+            "refresh_token": cred.refresh_token,
+            "client_id": cred.client_id,
+            "client_secret": cred.client_secret,
+        }, expected=(200,))
+        if "error" in result:
+            return None
+        data = result["result"]
+        cred.access_token = data["access_token"]
+        cred.token_expiry = time.time() + data.get("expires_in", 5184000) - 86400
+        save_credential(self.spec.cred_file, cred)
+        self._cred = cred
+        return cred.access_token
+
+    # --- Profile ---
+    def get_user_profile(self) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/userinfo",
+            headers={"Authorization": f"Bearer {self._ensure_token()}"},
+            expected=(200,),
+            transform=lambda d: {
+                "linkedin_id": d.get("sub"), "name": d.get("name"),
+                "given_name": d.get("given_name"), "family_name": d.get("family_name"),
+                "email": d.get("email"), "picture": d.get("picture"),
+            },
+        )
+
+    def get_profile_details(self) -> Result:
+        return http_request("GET", f"{LINKEDIN_API_BASE}/me", headers=self._headers(), expected=(200,))
+
+    # --- Connections ---
+    def get_connections(self, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/connections", headers=self._headers(),
+            params={"q": "viewer", "count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+
+    # --- Search ---
+    def search_people(self, keywords: str, count: int = 25, start: int = 0) -> Result:
+        result = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/people", headers=self._headers(),
+            params={"q": "search", "keywords": keywords, "count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+        if "error" in result:
+            result["note"] = "People search may require specific API access."
+        return result
+
+    def search_jobs(self, keywords: str, location: Optional[str] = None, count: int = 25, start: int = 0) -> Result:
+        params: Dict[str, Any] = {"keywords": keywords, "count": min(count, 50), "start": start}
+        if location:
+            params["locationGeoUrn"] = location
+        result = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/jobSearch", headers=self._headers(),
+            params=params, expected=(200,),
+        )
+        if "error" in result:
+            result["note"] = "LinkedIn Job Search API access may be restricted."
+        return result
+
+    def get_job_details(self, job_id: str) -> Result:
+        return http_request("GET", f"{LINKEDIN_API_BASE}/jobs/{job_id}", headers=self._headers(), expected=(200,))
+
+    def search_companies(self, keywords: str, count: int = 25, start: int = 0) -> Result:
+        result = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizationLookup", headers=self._headers(),
+            params={"q": "vanityName", "vanityName": keywords}, expected=(200,),
+        )
+        if "ok" in result:
+            return result
+        alt = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizations", headers=self._headers(),
+            params={"q": "search", "keywords": keywords, "count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+        return alt if "ok" in alt else result
+
+    def get_company_by_vanity_name(self, vanity_name: str) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizations", headers=self._headers(),
+            params={"q": "vanityName", "vanityName": vanity_name}, expected=(200,),
+        )
+
+    def get_person(self, person_id: str) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/people/(id:{person_id})",
+            headers=self._headers(), expected=(200,),
+        )
+
+    # --- Organizations ---
+    def get_my_organizations(self) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizationAcls", headers=self._headers(),
+            params={"q": "roleAssignee", "role": "ADMINISTRATOR",
+                    "projection": "(elements*(organization~,roleAssignee))"},
+            expected=(200,),
+        )
+
+    def get_organization(self, organization_id: str) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizations/{organization_id}",
+            headers=self._headers(), expected=(200,),
+        )
+
+    def get_organization_followers_count(self, organization_urn: str) -> Result:
+        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizationalEntityFollowerStatistics",
+            headers=self._headers(),
+            params={"q": "organizationalEntity",
+                    "organizationalEntity": f"urn:li:organization:{org_id}"},
+            expected=(200,),
+        )
+
+    # --- Posts ---
+    def _post_ugc(self, payload: Dict[str, Any]) -> Result:
+        return http_request("POST", f"{LINKEDIN_API_BASE}/ugcPosts",
+                            headers=self._headers(), json=payload)
+
+    def _share_payload(self, author_urn: str, text: str, media_category: str,
+                       media: Optional[List[Dict[str, Any]]] = None,
+                       visibility: str = "PUBLIC") -> Dict[str, Any]:
+        share: Dict[str, Any] = {
+            "shareCommentary": {"text": text[:3000] if text else ""},
+            "shareMediaCategory": media_category,
+        }
+        if media:
+            share["media"] = media
+        return {
+            "author": author_urn, "lifecycleState": "PUBLISHED",
+            "specificContent": {"com.linkedin.ugc.ShareContent": share},
+            "visibility": {"com.linkedin.ugc.MemberNetworkVisibility": visibility},
+        }
+
+    def create_text_post(self, author_urn: str, text: str, visibility: str = "PUBLIC") -> Result:
+        return self._post_ugc(self._share_payload(author_urn, text, "NONE", visibility=visibility))
+
+    def create_article_post(self, author_urn: str, text: str, link_url: str,
+                            link_title: str = "", link_description: str = "",
+                            visibility: str = "PUBLIC") -> Result:
+        media_item: Dict[str, Any] = {"status": "READY", "originalUrl": link_url}
+        if link_title:
+            media_item["title"] = {"text": link_title}
+        if link_description:
+            media_item["description"] = {"text": link_description}
+        return self._post_ugc(self._share_payload(author_urn, text, "ARTICLE", [media_item], visibility))
+
+    def create_image_post(self, author_urn: str, text: str, image_url: str,
+                          image_title: str = "", visibility: str = "PUBLIC") -> Result:
+        media = [{"status": "READY", "originalUrl": image_url, "title": {"text": image_title or ""}}]
+        return self._post_ugc(self._share_payload(author_urn, text, "IMAGE", media, visibility))
+
+    def reshare_post(self, author_urn: str, original_post_urn: str,
+                     commentary: str = "", visibility: str = "PUBLIC") -> Result:
+        media = [{"status": "READY",
+                  "originalUrl": f"https://www.linkedin.com/feed/update/{original_post_urn}"}]
+        return self._post_ugc(self._share_payload(author_urn, commentary, "ARTICLE", media, visibility))
+
+    def delete_post(self, post_urn: str) -> Result:
+        return http_request(
+            "DELETE", f"{LINKEDIN_API_BASE}/ugcPosts/{_encode_urn(post_urn)}",
+            headers=self._headers(), expected=(200, 204),
+            transform=lambda _d: {"deleted": True},
+        )
+
+    def get_post(self, post_urn: str) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/ugcPosts/{_encode_urn(post_urn)}",
+            headers=self._headers(), expected=(200,),
+        )
+
+    def get_posts_by_author(self, author_urn: str, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/ugcPosts", headers=self._headers(),
+            params={"q": "authors", "authors": f"List({author_urn})",
+                    "count": min(count, 100), "start": start},
+            expected=(200,),
+        )
+
+    # --- Messaging ---
+    def send_message_to_recipients(self, sender_urn: str, recipient_urns: List[str],
+                                   subject: str, body: str) -> Result:
+        result = http_request(
+            "POST", f"{LINKEDIN_API_BASE}/messages", headers=self._headers(),
+            json={"recipients": recipient_urns, "subject": subject, "body": body},
+        )
+        if "error" in result:
+            result["note"] = "Messaging API requires special permissions."
+        elif result.get("result") is None:
+            result["result"] = {"sent": True}
+        return result
+
+    # --- Invitations ---
+    def send_connection_request(self, invitee_profile_urn: str, message: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"invitee": invitee_profile_urn}
+        if message:
+            payload["message"] = message[:300]
+        result = http_request("POST", f"{LINKEDIN_API_BASE}/invitations",
+                              headers=self._headers(), json=payload)
+        if "ok" in result and result.get("result") is None:
+            result["result"] = {"sent": True}
+        return result
+
+    def withdraw_connection_request(self, invitation_urn: str) -> Result:
+        return http_request(
+            "DELETE", f"{LINKEDIN_API_BASE}/invitations/{_encode_urn(invitation_urn)}",
+            headers=self._headers(), expected=(200, 204),
+            transform=lambda _d: {"withdrawn": True},
+        )
+
+    def get_sent_invitations(self, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/invitations", headers=self._headers(),
+            params={"q": "inviter", "count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+
+    def get_received_invitations(self, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/invitations", headers=self._headers(),
+            params={"q": "invitee", "count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+
+    def respond_to_invitation(self, invitation_urn: str, action: str) -> Result:
+        return http_request(
+            "PATCH", f"{LINKEDIN_API_BASE}/invitations/{_encode_urn(invitation_urn)}",
+            headers=self._headers(), json={"action": action.upper()},
+            expected=(200, 204),
+            transform=lambda _d: {"action": action, "completed": True},
+        )
+
+    # --- Conversations ---
+    def get_conversations(self, count: int = 20, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/conversations", headers=self._headers(),
+            params={"count": min(count, 50), "start": start},
+            expected=(200,),
+        )
+
+    # --- Likes ---
+    def like_post(self, actor_urn: str, post_urn: str) -> Result:
+        result = http_request(
+            "POST", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes",
+            headers=self._headers(), json={"actor": actor_urn},
+        )
+        if "ok" in result and result.get("result") is None:
+            result["result"] = {"liked": True}
+        return result
+
+    def unlike_post(self, actor_urn: str, post_urn: str) -> Result:
+        composite_key = quote(f"(liker:{actor_urn})", safe="")
+        return http_request(
+            "DELETE", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes/{composite_key}",
+            headers=self._headers(), expected=(200, 204),
+            transform=lambda _d: {"unliked": True},
+        )
+
+    def get_post_reactions(self, post_urn: str, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/likes",
+            headers=self._headers(),
+            params={"count": min(count, 100), "start": start},
+            expected=(200,),
+        )
+
+    # --- Comments ---
+    def comment_on_post(self, actor_urn: str, post_urn: str, text: str,
+                        parent_comment_urn: Optional[str] = None) -> Result:
+        payload: Dict[str, Any] = {"actor": actor_urn, "message": {"text": text[:1250]}}
+        if parent_comment_urn:
+            payload["parentComment"] = parent_comment_urn
+        return http_request(
+            "POST", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments",
+            headers=self._headers(), json=payload,
+        )
+
+    def get_post_comments(self, post_urn: str, count: int = 50, start: int = 0) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments",
+            headers=self._headers(),
+            params={"count": min(count, 100), "start": start},
+            expected=(200,),
+        )
+
+    def delete_comment(self, actor_urn: str, post_urn: str, comment_urn: str) -> Result:
+        return http_request(
+            "DELETE", f"{LINKEDIN_API_BASE}/socialActions/{_encode_urn(post_urn)}/comments/{_encode_urn(comment_urn)}",
+            headers=self._headers(), params={"actor": actor_urn},
+            expected=(200, 204),
+            transform=lambda _d: {"deleted": True},
+        )
+
+    # --- Analytics ---
+    def get_post_analytics(self, share_urns: List[str]) -> Result:
+        primary = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizationalEntityShareStatistics",
+            headers=self._headers(),
+            params={"q": "organizationalEntity", "shares": ",".join(share_urns)},
+            expected=(200,),
+        )
+        if "ok" in primary:
+            return primary
+        alt = http_request(
+            "GET", f"{LINKEDIN_API_BASE}/socialMetadata", headers=self._headers(),
+            params={"ids": f"List({','.join(share_urns)})"},
+            expected=(200,),
+        )
+        return alt if "ok" in alt else primary
+
+    def get_social_metadata(self, post_urn: str) -> Result:
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/socialMetadata/{_encode_urn(post_urn)}",
+            headers=self._headers(), expected=(200,),
+        )
+
+    def get_organization_analytics(self, organization_urn: str) -> Result:
+        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
+        return http_request(
+            "GET", f"{LINKEDIN_API_BASE}/organizationPageStatistics",
+            headers=self._headers(),
+            params={"q": "organization", "organization": f"urn:li:organization:{org_id}"},
+            expected=(200,),
+        )
+
+    # --- Follow ---
+    def follow_organization(self, follower_urn: str, organization_urn: str) -> Result:
+        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
+        result = http_request(
+            "POST", f"{LINKEDIN_API_BASE}/organizationFollows",
+            headers=self._headers(),
+            json={"followee": f"urn:li:organization:{org_id}", "follower": follower_urn},
+        )
+        if "ok" in result and result.get("result") is None:
+            result["result"] = {"following": True}
+        return result
+
+    def unfollow_organization(self, follower_urn: str, organization_urn: str) -> Result:
+        org_id = organization_urn.split(":")[-1] if ":" in organization_urn else organization_urn
+        followee_urn = f"urn:li:organization:{org_id}"
+        return http_request(
+            "DELETE",
+            f"{LINKEDIN_API_BASE}/organizationFollows/follower={_encode_urn(follower_urn)}&followee={_encode_urn(followee_urn)}",
+            headers=self._headers(), expected=(200, 204),
+            transform=lambda _d: {"unfollowed": True},
+        )
+
+    # --- Media upload ---
+    def register_image_upload(self, owner_urn: str) -> Result:
+        def _shape(data):
+            upload_info = data.get("value", {})
+            upload_mechanism = upload_info.get("uploadMechanism", {})
+            media_upload = upload_mechanism.get("com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest", {})
+            return {
+                "upload_url": media_upload.get("uploadUrl"),
+                "asset": upload_info.get("asset"),
+                "full_response": data,
+            }
+
+        return http_request(
+            "POST", f"{LINKEDIN_API_BASE}/assets?action=registerUpload",
+            headers=self._headers(),
+            json={"registerUploadRequest": {
+                "recipes": ["urn:li:digitalmediaRecipe:feedshare-image"],
+                "owner": owner_urn,
+                "serviceRelationships": [
+                    {"relationshipType": "OWNER", "identifier": "urn:li:userGeneratedContent"}
+                ],
+            }},
+            transform=_shape,
+        )
+
+    def upload_image_binary(self, upload_url: str, image_data: bytes) -> Result:
+        import httpx
+        try:
+            r = httpx.put(
+                upload_url,
+                headers={"Authorization": f"Bearer {self._ensure_token()}",
+                         "Content-Type": "application/octet-stream"},
+                content=image_data, timeout=60.0,
+            )
+            if r.status_code in (200, 201):
+                return {"ok": True, "result": {"uploaded": True}}
+            return {"error": f"API error: {r.status_code}", "details": r.text}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def create_post_with_uploaded_image(self, author_urn: str, text: str, asset_urn: str,
+                                         image_title: str = "", visibility: str = "PUBLIC") -> Result:
+        media = [{"status": "READY", "media": asset_urn, "title": {"text": image_title or ""}}]
+        return self._post_ugc(self._share_payload(author_urn, text, "IMAGE", media, visibility))
diff --git a/craftos_integrations/integrations/notion/INTEGRATION.md b/craftos_integrations/integrations/notion/INTEGRATION.md
new file mode 100644
index 00000000..faea411e
--- /dev/null
+++ b/craftos_integrations/integrations/notion/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Notion — Integration Reference
+
+REST integration via an internal integration token (or OAuth). Query and edit pages and databases. Query-only — does not listen for changes.
+
+## Essentials
+
+- **No event listening.** `supports_listening = False`. Notion will never push incoming messages to the router — it's request-response only. Don't promise the user "you'll be notified when X changes."
+- **IDs are 36-char UUIDs with hyphens, not human-readable names.** Always `search_notion` first to resolve a name like "Roadmap" to its page or database ID.
+- **`create_notion_page` requires `parent_type` AND matching `parent_id`.** `parent_type` is either `"page_id"` or `"database_id"`. Mismatched type → server-side failure. The parent must already exist.
+- **Page content is Notion block JSON, not markdown.** `append_notion_page_content` expects rich Notion block objects (paragraph, heading_1, bulleted_list_item, etc.) — passing markdown silently fails. If the user gives markdown, the router must convert.
+- **Database properties are typed nested objects, not flat strings.** Before `update_notion_page` on a database row, call `get_notion_database_schema` to learn each property's type (title vs rich_text vs select vs date), then build the correctly-shaped object.
+- **An integration only sees pages it's been explicitly shared with.** "Notion can't find the page" usually means the user hasn't invited the integration to that page — direct them to the page's "..." → "Add connections" menu, not a retry.
diff --git a/craftos_integrations/integrations/notion/__init__.py b/craftos_integrations/integrations/notion/__init__.py
new file mode 100644
index 00000000..12c2bda1
--- /dev/null
+++ b/craftos_integrations/integrations/notion/__init__.py
@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+"""Notion integration - handler (token + OAuth invite) + client."""
+from __future__ import annotations
+
+import json as _json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    OAuthFlow,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+NOTION_API_BASE = "https://api.notion.com/v1"
+NOTION_VERSION = "2022-06-28"
+
+
+def _notion_call(method: str, path: str, headers: Dict[str, str], **kw) -> Dict[str, Any]:
+    """Notion API call. Returns raw response on 200, ``{error: <notion-body>}`` otherwise.
+
+    Layers on top of ``request`` and re-parses ``details`` (string) back into Notion's
+    JSON error body so callers can read ``result["error"]["code"]`` etc.
+    """
+    result = http_request(
+        method, f"{NOTION_API_BASE}{path}",
+        headers=headers, expected=(200,), **kw,
+    )
+    if "error" not in result:
+        return result["result"]
+    details = result.get("details")
+    if isinstance(details, str):
+        try:
+            return {"error": _json.loads(details)}
+        except Exception:
+            pass
+    return {"error": {"exception": result["error"]}}
+
+
+@dataclass
+class NotionCredential:
+    token: str = ""
+
+
+NOTION = IntegrationSpec(
+    name="notion",
+    cred_class=NotionCredential,
+    cred_file="notion.json",
+    platform_id="notion",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(NOTION.name)
+class NotionHandler(IntegrationHandler):
+    spec = NOTION
+    display_name = "Notion"
+    description = "Notes and databases"
+    auth_type = "both"  # OAuth invite + raw integration token
+    icon = "notion"
+    connect_help = [
+        "Open notion.so/my-integrations",
+        "Click 'New integration', give it a name and pick the workspace",
+        "Copy the 'Internal Integration Token' (starts with secret_)",
+        "In Notion, share each page/database you want CraftBot to access with the integration",
+    ]
+    fields = [
+        {"key": "token", "label": "Integration Token", "placeholder": "secret_...", "password": True},
+    ]
+
+    oauth = OAuthFlow(
+        client_id_key="NOTION_SHARED_CLIENT_ID",
+        client_secret_key="NOTION_SHARED_CLIENT_SECRET",
+        auth_url="https://api.notion.com/v1/oauth/authorize",
+        token_url="https://api.notion.com/v1/oauth/token",
+        userinfo_url=None,
+        scopes="",
+        token_auth_basic=True,
+        token_request_json=True,
+        extra_auth_params={"owner": "user"},
+    )
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["invite", "login", "logout", "status"]
+
+    async def invite(self, args: List[str]) -> Tuple[bool, str]:
+        result = await self.oauth.run()
+        if "error" in result and not result.get("access_token"):
+            return False, f"Notion OAuth failed: {result['error']}"
+
+        token = result.get("access_token", "")
+        ws_name = result.get("raw", {}).get("workspace_name", "default")
+        save_credential(self.spec.cred_file, NotionCredential(token=token))
+        return True, f"Notion connected via CraftOS integration: {ws_name}"
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, "Usage: /notion login <integration_token>"
+        token = args[0]
+
+        data = _notion_call(
+            "GET", "/users/me",
+            {"Authorization": f"Bearer {token}", "Notion-Version": NOTION_VERSION},
+        )
+        if "error" in data:
+            return False, f"Notion auth failed: {data['error']}"
+
+        ws_name = data.get("bot", {}).get("workspace_name", "default")
+        save_credential(self.spec.cred_file, NotionCredential(token=token))
+        return True, f"Notion connected: {ws_name}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Notion credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Notion credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Notion: Not connected"
+        return True, "Notion: Connected"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class NotionClient(BasePlatformClient):
+    spec = NOTION
+    PLATFORM_ID = NOTION.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[NotionCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> NotionCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, NotionCredential)
+        if self._cred is None:
+            raise RuntimeError("No Notion credentials. Use /notion login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        return {
+            "Authorization": f"Bearer {cred.token}",
+            "Content-Type": "application/json",
+            "Notion-Version": NOTION_VERSION,
+        }
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+        return {"ok": False, "error": "Notion does not support messaging"}
+
+    def search(self, query: str, filter_type: Optional[str] = None, page_size: int = 100) -> List[Dict[str, Any]]:
+        payload: Dict[str, Any] = {"query": query, "page_size": page_size}
+        if filter_type in ("page", "database"):
+            payload["filter"] = {"property": "object", "value": filter_type}
+        data = _notion_call("POST", "/search", self._headers(), json=payload)
+        if "error" in data:
+            return [{"error": data["error"]}]
+        return data.get("results", [])
+
+    def get_page(self, page_id: str) -> Dict[str, Any]:
+        return _notion_call("GET", f"/pages/{page_id}", self._headers())
+
+    def get_database(self, database_id: str) -> Dict[str, Any]:
+        return _notion_call("GET", f"/databases/{database_id}", self._headers())
+
+    def query_database(
+        self,
+        database_id: str,
+        filter_obj: Optional[Dict[str, Any]] = None,
+        sorts: Optional[List[Dict[str, Any]]] = None,
+        page_size: int = 100,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"page_size": page_size}
+        if filter_obj:
+            payload["filter"] = filter_obj
+        if sorts:
+            payload["sorts"] = sorts
+        return _notion_call("POST", f"/databases/{database_id}/query", self._headers(), json=payload)
+
+    def create_page(
+        self,
+        parent_id: str,
+        parent_type: str,
+        properties: Dict[str, Any],
+        children: Optional[List[Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"parent": {parent_type: parent_id}, "properties": properties}
+        if children:
+            payload["children"] = children
+        return _notion_call("POST", "/pages", self._headers(), json=payload)
+
+    def update_page(self, page_id: str, properties: Dict[str, Any]) -> Dict[str, Any]:
+        return _notion_call("PATCH", f"/pages/{page_id}", self._headers(), json={"properties": properties})
+
+    def get_block_children(self, block_id: str, page_size: int = 100) -> Dict[str, Any]:
+        return _notion_call("GET", f"/blocks/{block_id}/children", self._headers(), params={"page_size": page_size})
+
+    def append_block_children(self, block_id: str, children: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return _notion_call("PATCH", f"/blocks/{block_id}/children", self._headers(), json={"children": children})
+
+    def delete_block(self, block_id: str) -> Dict[str, Any]:
+        return _notion_call("DELETE", f"/blocks/{block_id}", self._headers())
+
+    def get_user(self, user_id: str = "me") -> Dict[str, Any]:
+        return _notion_call("GET", f"/users/{user_id}", self._headers())
diff --git a/craftos_integrations/integrations/outlook/INTEGRATION.md b/craftos_integrations/integrations/outlook/INTEGRATION.md
new file mode 100644
index 00000000..05db362b
--- /dev/null
+++ b/craftos_integrations/integrations/outlook/INTEGRATION.md
@@ -0,0 +1,14 @@
+# Outlook — Integration Reference
+
+Microsoft 365 / Outlook.com mail integration via Microsoft Graph.
+
+## Essentials
+
+- **The integration knows the user's own email address** (`cred.email`). NEVER ask the user — read it from the connected credential or `check_integration_status`.
+- **`From` is always the connected account.** Can't be spoofed on send.
+- **Self-emails are auto-filtered on incoming events** (case-insensitive match on sender) — own sends don't echo back.
+- **Identity format:** plain email-address strings.
+- **Message IDs are Microsoft Graph opaque IDs** (`AAMk...`). Pull from list/search; never construct.
+- **Conversation IDs group related messages** — useful for finding threads.
+- **Token refresh is automatic** (60-second buffer before 2-hour TTL). A 401 means the access token expired and the client is refreshing — wait and retry. Only direct the user to reconnect if 401s persist across retries.
+- **Poll filter field is `receivedDateTime`** (ISO 8601). Time-windowed reads use this field.
diff --git a/craftos_integrations/integrations/outlook/__init__.py b/craftos_integrations/integrations/outlook/__init__.py
new file mode 100644
index 00000000..26dee833
--- /dev/null
+++ b/craftos_integrations/integrations/outlook/__init__.py
@@ -0,0 +1,401 @@
+# -*- coding: utf-8 -*-
+"""Outlook integration - Microsoft Graph + OAuth (PKCE)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional, List, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    OAuthFlow,
+    PlatformMessage,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...config import ConfigStore
+from ...helpers import Result, arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+GRAPH_API_BASE = "https://graph.microsoft.com/v1.0"
+MS_TOKEN_URL = "https://login.microsoftonline.com/common/oauth2/v2.0/token"
+OUTLOOK_SCOPES = "Mail.Read Mail.Send Mail.ReadWrite User.Read offline_access"
+
+POLL_INTERVAL = 5
+RETRY_DELAY = 10
+
+
+@dataclass
+class OutlookCredential:
+    access_token: str = ""
+    refresh_token: str = ""
+    token_expiry: float = 0.0
+    client_id: str = ""
+    email: str = ""
+
+
+OUTLOOK = IntegrationSpec(
+    name="outlook",
+    cred_class=OutlookCredential,
+    cred_file="outlook.json",
+    platform_id="outlook",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(OUTLOOK.name)
+class OutlookHandler(IntegrationHandler):
+    spec = OUTLOOK
+    display_name = "Outlook"
+    description = "Microsoft email and calendar"
+    auth_type = "oauth"
+    icon = "Inbox"
+    fields: List = []
+
+    oauth = OAuthFlow(
+        client_id_key="OUTLOOK_CLIENT_ID",
+        client_secret_key=None,
+        auth_url="https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+        token_url=MS_TOKEN_URL,
+        userinfo_url="https://graph.microsoft.com/v1.0/me",
+        scopes=OUTLOOK_SCOPES,
+        use_pkce=True,
+        extra_auth_params={"response_mode": "query"},
+    )
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        result = await self.oauth.run()
+        if "error" in result and not result.get("access_token"):
+            return False, f"Outlook OAuth failed: {result['error']}"
+
+        info = result.get("userinfo", {})
+        user_email = info.get("mail") or info.get("userPrincipalName", "")
+
+        save_credential(self.spec.cred_file, OutlookCredential(
+            access_token=result["access_token"],
+            refresh_token=result.get("refresh_token", ""),
+            token_expiry=time.time() + result.get("expires_in", 3600),
+            client_id=ConfigStore.get_oauth("OUTLOOK_CLIENT_ID"),
+            email=user_email,
+        ))
+        return True, f"Outlook connected as {user_email}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Outlook credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Outlook credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Outlook: Not connected"
+        cred = load_credential(self.spec.cred_file, OutlookCredential)
+        email = cred.email if cred else "unknown"
+        return True, f"Outlook: Connected\n  - {email}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class OutlookClient(BasePlatformClient):
+    spec = OUTLOOK
+    PLATFORM_ID = OUTLOOK.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[OutlookCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._seen_message_ids: set = set()
+        self._last_poll_time: Optional[str] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> OutlookCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, OutlookCredential)
+        if self._cred is None:
+            raise RuntimeError("No Outlook credentials. Use /outlook login first.")
+        return self._cred
+
+    def _ensure_token(self) -> str:
+        cred = self._load()
+        if cred.refresh_token and cred.token_expiry and time.time() > cred.token_expiry:
+            result = self.refresh_access_token()
+            if result:
+                return result
+        return cred.access_token
+
+    def refresh_access_token(self) -> Optional[str]:
+        cred = self._load()
+        if not all([cred.client_id, cred.refresh_token]):
+            return None
+        result = http_request("POST", MS_TOKEN_URL, data={
+            "client_id": cred.client_id,
+            "refresh_token": cred.refresh_token,
+            "grant_type": "refresh_token",
+            "scope": OUTLOOK_SCOPES,
+        }, expected=(200,))
+        if "error" in result:
+            return None
+        data = result["result"]
+        cred.access_token = data["access_token"]
+        cred.refresh_token = data.get("refresh_token", cred.refresh_token)
+        cred.token_expiry = time.time() + data.get("expires_in", 3600) - 60
+        save_credential(self.spec.cred_file, cred)
+        self._cred = cred
+        return cred.access_token
+
+    def _headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._ensure_token()}", "Content-Type": "application/json"}
+
+    def _auth_header(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self._ensure_token()}"}
+
+    async def connect(self) -> None:
+        cred = self._load()
+        if not cred.access_token:
+            raise RuntimeError("Outlook credentials need to be updated. Run /outlook logout then /outlook login.")
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return self.send_email(to=recipient, subject=kwargs.get("subject", ""), body=text)
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        self._load()
+
+        try:
+            profile = await self._async_get_profile()
+            email_addr = profile.get("mail") or profile.get("userPrincipalName", "")
+            logger.info(f"[OUTLOOK] Connected as: {email_addr}")
+        except Exception as e:
+            raise RuntimeError(f"Failed to connect to Outlook: {e}")
+
+        self._last_poll_time = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    async def _async_get_profile(self) -> Dict[str, Any]:
+        result = await arequest("GET", f"{GRAPH_API_BASE}/me", headers=self._auth_header(), expected=(200,))
+        if "error" in result:
+            raise RuntimeError(f"Graph /me {result['error']}")
+        return result["result"]
+
+    async def _poll_loop(self) -> None:
+        while self._listening:
+            try:
+                await self._check_new_messages()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[OUTLOOK] Poll error: {e}")
+                if "401" in str(e):
+                    self.refresh_access_token()
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    async def _check_new_messages(self) -> None:
+        if not self._last_poll_time:
+            return
+        result = await arequest(
+            "GET", f"{GRAPH_API_BASE}/me/messages",
+            headers=self._auth_header(),
+            params={
+                "$filter": f"receivedDateTime ge {self._last_poll_time}",
+                "$orderby": "receivedDateTime asc",
+                "$top": "50",
+                "$select": "id,from,subject,bodyPreview,receivedDateTime,conversationId",
+            },
+            expected=(200,),
+        )
+        if "error" in result:
+            if "401" in result["error"]:
+                self.refresh_access_token()
+            else:
+                logger.warning(f"[OUTLOOK] messages API {result['error']}")
+            return
+
+        messages = (result["result"] or {}).get("value", [])
+        for msg in messages:
+            msg_id = msg.get("id", "")
+            if not msg_id or msg_id in self._seen_message_ids:
+                continue
+            self._seen_message_ids.add(msg_id)
+            await self._dispatch_message(msg)
+
+        if messages:
+            last_received = messages[-1].get("receivedDateTime", "")
+            if last_received:
+                self._last_poll_time = last_received
+
+        if len(self._seen_message_ids) > 500:
+            self._seen_message_ids = set(list(self._seen_message_ids)[-200:])
+
+    async def _dispatch_message(self, msg: Dict[str, Any]) -> None:
+        from_obj = msg.get("from", {}).get("emailAddress", {})
+        sender_email = from_obj.get("address", "")
+        sender_name = from_obj.get("name", sender_email)
+
+        cred = self._load()
+        if sender_email.lower() == (cred.email or "").lower():
+            return
+
+        subject = msg.get("subject", "(no subject)")
+        snippet = msg.get("bodyPreview", "")
+        text = f"Subject: {subject}\n{snippet}" if snippet else f"Subject: {subject}"
+
+        timestamp = None
+        try:
+            timestamp = datetime.fromisoformat(msg.get("receivedDateTime", "").replace("Z", "+00:00"))
+        except Exception:
+            pass
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=sender_email,
+                sender_name=sender_name,
+                text=text,
+                channel_id=msg.get("conversationId", ""),
+                message_id=msg.get("id", ""),
+                timestamp=timestamp,
+                raw=msg,
+            ))
+
+    # --- Email API ---
+    def send_email(self, to: str, subject: str, body: str, cc: Optional[str] = None,
+                   html: bool = False) -> Result:
+        content_type = "HTML" if html else "Text"
+        message: Dict[str, Any] = {
+            "subject": subject,
+            "body": {"contentType": content_type, "content": body},
+            "toRecipients": [{"emailAddress": {"address": to}}],
+        }
+        if cc:
+            message["ccRecipients"] = [{"emailAddress": {"address": addr.strip()}} for addr in cc.split(",")]
+        return http_request(
+            "POST", f"{GRAPH_API_BASE}/me/sendMail",
+            headers=self._headers(),
+            json={"message": message, "saveToSentItems": True},
+            expected=(202,),
+            transform=lambda _d: {"sent": True, "to": to, "subject": subject},
+        )
+
+    def list_emails(self, n: int = 10, unread_only: bool = False, folder: str = "inbox") -> Result:
+        params: Dict[str, Any] = {
+            "$top": n, "$orderby": "receivedDateTime desc",
+            "$select": "id,from,subject,receivedDateTime,isRead,bodyPreview",
+        }
+        if unread_only:
+            params["$filter"] = "isRead eq false"
+
+        def _shape(d):
+            emails = []
+            for msg in d.get("value", []):
+                from_obj = msg.get("from", {}).get("emailAddress", {})
+                emails.append({
+                    "id": msg.get("id"),
+                    "from": f"{from_obj.get('name', '')} <{from_obj.get('address', '')}>",
+                    "subject": msg.get("subject", ""),
+                    "date": msg.get("receivedDateTime", ""),
+                    "is_read": msg.get("isRead", False),
+                    "preview": msg.get("bodyPreview", ""),
+                })
+            return {"emails": emails, "count": len(emails)}
+
+        return http_request(
+            "GET", f"{GRAPH_API_BASE}/me/mailFolders/{folder}/messages",
+            headers=self._auth_header(), params=params,
+            expected=(200,), transform=_shape,
+        )
+
+    def get_email(self, message_id: str) -> Result:
+        def _shape(msg):
+            from_obj = msg.get("from", {}).get("emailAddress", {})
+            to_list = [
+                f"{rcpt.get('emailAddress', {}).get('name', '')} <{rcpt.get('emailAddress', {}).get('address', '')}>"
+                for rcpt in msg.get("toRecipients", [])
+            ]
+            return {
+                "id": msg.get("id"),
+                "from": f"{from_obj.get('name', '')} <{from_obj.get('address', '')}>",
+                "to": ", ".join(to_list),
+                "subject": msg.get("subject", ""),
+                "date": msg.get("receivedDateTime", ""),
+                "body": msg.get("body", {}).get("content", ""),
+            }
+
+        return http_request(
+            "GET", f"{GRAPH_API_BASE}/me/messages/{message_id}",
+            headers=self._auth_header(),
+            params={"$select": "id,from,toRecipients,subject,body,receivedDateTime,conversationId"},
+            expected=(200,), transform=_shape,
+        )
+
+    def mark_as_read(self, message_id: str) -> Result:
+        return http_request(
+            "PATCH", f"{GRAPH_API_BASE}/me/messages/{message_id}",
+            headers=self._headers(), json={"isRead": True},
+            expected=(200,), transform=lambda _d: {},
+        )
+
+    def list_folders(self) -> Result:
+        return http_request(
+            "GET", f"{GRAPH_API_BASE}/me/mailFolders",
+            headers=self._auth_header(),
+            params={"$select": "id,displayName,totalItemCount,unreadItemCount"},
+            expected=(200,),
+            transform=lambda d: {"folders": [
+                {"id": f.get("id"), "name": f.get("displayName"),
+                 "total": f.get("totalItemCount"), "unread": f.get("unreadItemCount")}
+                for f in d.get("value", [])
+            ]},
+        )
+
+    def read_top_emails(self, n: int = 5, full_body: bool = False) -> Result:
+        listing = self.list_emails(n=n, unread_only=False)
+        if "error" in listing:
+            return listing
+        emails_summary = listing.get("result", {}).get("emails", [])
+        if not full_body:
+            return {"ok": True, "result": emails_summary}
+        detailed = []
+        for e_info in emails_summary:
+            detail = self.get_email(e_info["id"])
+            detailed.append(detail.get("result", e_info) if "error" not in detail else e_info)
+        return {"ok": True, "result": detailed}
diff --git a/craftos_integrations/integrations/slack/INTEGRATION.md b/craftos_integrations/integrations/slack/INTEGRATION.md
new file mode 100644
index 00000000..502db45b
--- /dev/null
+++ b/craftos_integrations/integrations/slack/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Slack — Integration Reference
+
+Bot-token integration. Send/receive messages, list channels, search history, upload files. Talks to Slack's Web API.
+
+## Essentials
+
+- **Channel ID prefix tells you what it is:** `C...` = public channel, `G...` = private channel/group, `D...` = direct message channel, `U...` = user ID (NOT a channel — can't send to it directly). The Slack API never accepts channel NAMES — always IDs. Use `list_slack_channels` to translate.
+- **DMs need a `D...` channel ID,** not a user ID. Open the DM channel first via `open_slack_dm` to get its `D...` id; sending to a user id is an error.
+- **Thread replies:** pass `thread_ts` (a float-as-string like `"1234567890.123456"`) to `send_slack_message`. Without it, the message goes to the channel root, not the thread.
+- **Session-level facts the integration knows:** `team_name`, `workspace_id`, `bot_user_id`. Resolved at login — use `get_slack_channel_info` / `list_slack_users` instead of asking the user.
+- **Error envelope:** Slack returns `{"ok": false, "error": "..."}`. Common: `channel_not_found` or `not_in_channel` means the bot isn't a member of that channel — invite it; don't retry.
+- **Polling auto-drops broken channels:** if a channel keeps throwing `channel_not_found` during polling, the listener stops monitoring it silently. If incoming events stop arriving from one channel only, confirm the bot is still a member.
diff --git a/craftos_integrations/integrations/slack/__init__.py b/craftos_integrations/integrations/slack/__init__.py
new file mode 100644
index 00000000..1a7df2fc
--- /dev/null
+++ b/craftos_integrations/integrations/slack/__init__.py
@@ -0,0 +1,412 @@
+# -*- coding: utf-8 -*-
+"""Slack integration - handler (token + OAuth invite) + client (poll listener)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    OAuthFlow,
+    PlatformMessage,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+SLACK_API_BASE = "https://slack.com/api"
+SLACK_SCOPES = "chat:write,channels:read,channels:history,groups:read,groups:history,users:read,files:write,im:read,im:write,im:history"
+
+POLL_INTERVAL = 3
+RETRY_DELAY = 5
+
+
+def _shape_slack(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Apply Slack's ``{ok: bool, ...}`` envelope to an ``arequest``/``request`` result.
+
+    On HTTP success but ``ok=False`` returns ``{error, details}``. Otherwise returns
+    the raw Slack response (callers read fields like ``channels``, ``channel.id`` directly).
+    """
+    if "error" in result:
+        return result
+    body = result["result"]
+    if not body.get("ok"):
+        return {"error": body.get("error", "Unknown error"), "details": body}
+    return body
+
+
+def _slack_call(method: str, path: str, headers: Dict[str, str], **kw) -> Dict[str, Any]:
+    return _shape_slack(http_request(
+        method, f"{SLACK_API_BASE}/{path}", headers=headers, expected=(200,), **kw,
+    ))
+
+
+async def _slack_acall(method: str, path: str, headers: Dict[str, str], **kw) -> Dict[str, Any]:
+    return _shape_slack(await arequest(
+        method, f"{SLACK_API_BASE}/{path}", headers=headers, expected=(200,), **kw,
+    ))
+
+
+@dataclass
+class SlackCredential:
+    bot_token: str = ""
+    workspace_id: str = ""
+    team_name: str = ""
+
+
+SLACK = IntegrationSpec(
+    name="slack",
+    cred_class=SlackCredential,
+    cred_file="slack.json",
+    platform_id="slack",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(SLACK.name)
+class SlackHandler(IntegrationHandler):
+    spec = SLACK
+    display_name = "Slack"
+    description = "Team messaging"
+    auth_type = "both"  # OAuth invite + raw bot token
+    icon = "slack"
+    connect_help = [
+        "Open api.slack.com/apps",
+        "Click 'Create New App' → 'From scratch', pick your workspace",
+        "Open 'OAuth & Permissions' in the left sidebar",
+        "Add bot scopes: chat:write, channels:read, users:read (more as needed)",
+        "Click 'Install to Workspace' at the top, then copy the 'Bot User OAuth Token' (xoxb-...)",
+    ]
+    fields = [
+        {"key": "bot_token", "label": "Bot Token", "placeholder": "xoxb-...", "password": True},
+        {"key": "workspace_name", "label": "Workspace Name (optional)", "placeholder": "My Workspace", "password": False, "optional": True},
+    ]
+
+    oauth = OAuthFlow(
+        client_id_key="SLACK_SHARED_CLIENT_ID",
+        client_secret_key="SLACK_SHARED_CLIENT_SECRET",
+        auth_url="https://slack.com/oauth/v2/authorize",
+        token_url="https://slack.com/api/oauth.v2.access",
+        userinfo_url=None,
+        scopes=SLACK_SCOPES,
+        use_https=True,
+    )
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["invite", "login", "logout", "status"]
+
+    async def invite(self, args: List[str]) -> Tuple[bool, str]:
+        result = await self.oauth.run()
+        if "error" in result and not result.get("access_token"):
+            return False, f"Slack OAuth failed: {result['error']}"
+
+        raw = result.get("raw", {})
+        if not raw.get("ok"):
+            return False, f"Slack OAuth token exchange failed: {raw.get('error')}"
+
+        bot_token = raw.get("access_token", "")
+        team = raw.get("team", {})
+        team_id = team.get("id", "")
+        team_name = team.get("name", team_id)
+
+        save_credential(self.spec.cred_file, SlackCredential(
+            bot_token=bot_token, workspace_id=team_id, team_name=team_name,
+        ))
+        return True, f"Slack connected via CraftOS app: {team_name} ({team_id})"
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, "Usage: /slack login <bot_token> [workspace_name]"
+        bot_token = args[0]
+        if not bot_token.startswith(("xoxb-", "xoxp-")):
+            return False, "Invalid token. Expected xoxb-... or xoxp-..."
+
+        result = _slack_call("POST", "auth.test", {"Authorization": f"Bearer {bot_token}"})
+        if "error" in result:
+            return False, f"Slack auth failed: {result['error']}"
+        team_id = result.get("team_id", "")
+        workspace_name = args[1] if len(args) > 1 else result.get("team", team_id)
+
+        save_credential(self.spec.cred_file, SlackCredential(
+            bot_token=bot_token, workspace_id=team_id, team_name=workspace_name,
+        ))
+        return True, f"Slack connected: {workspace_name} ({team_id})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Slack credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Slack credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Slack: Not connected"
+        cred = load_credential(self.spec.cred_file, SlackCredential)
+        name = cred.team_name or cred.workspace_id if cred else "unknown"
+        return True, f"Slack: Connected\n  - {name} ({cred.workspace_id})"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class SlackClient(BasePlatformClient):
+    spec = SLACK
+    PLATFORM_ID = SLACK.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[SlackCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._bot_user_id: Optional[str] = None
+        self._last_timestamps: Dict[str, str] = {}
+        self._catchup_done: bool = False
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> SlackCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, SlackCredential)
+        if self._cred is None:
+            raise RuntimeError("No Slack credentials. Use /slack login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        return {"Authorization": f"Bearer {cred.bot_token}", "Content-Type": "application/json"}
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        cred = self._load()
+
+        data = await _slack_acall("POST", "auth.test", {"Authorization": f"Bearer {cred.bot_token}"})
+        if "error" in data:
+            raise RuntimeError(f"Invalid Slack token: {data['error']}")
+        self._bot_user_id = data.get("user_id")
+
+        logger.info(f"[SLACK] Bot user ID: {self._bot_user_id}")
+        self._listening = True
+        self._catchup_done = False
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    async def _poll_loop(self) -> None:
+        try:
+            await self._refresh_channel_timestamps()
+            self._catchup_done = True
+        except Exception as e:
+            logger.error(f"[SLACK] Catchup error: {e}")
+            self._catchup_done = True
+
+        while self._listening:
+            try:
+                await self._poll_channels()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[SLACK] Poll error: {e}")
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    async def _get_joined_channels(self) -> List[Dict[str, Any]]:
+        channels: List[Dict[str, Any]] = []
+        for ch_type in ("public_channel,private_channel", "mpim,im"):
+            cursor = None
+            while True:
+                params: Dict[str, Any] = {"types": ch_type, "exclude_archived": True, "limit": 200}
+                if cursor:
+                    params["cursor"] = cursor
+                data = await _slack_acall("GET", "conversations.list", self._headers(), params=params)
+                if "error" in data:
+                    break
+                for ch in data.get("channels", []):
+                    if ch.get("is_member") or ch.get("is_im") or ch.get("is_mpim"):
+                        channels.append(ch)
+                cursor = data.get("response_metadata", {}).get("next_cursor")
+                if not cursor:
+                    break
+        return channels
+
+    async def _refresh_channel_timestamps(self) -> None:
+        now_ts = f"{time.time():.6f}"
+        channels = await self._get_joined_channels()
+        for ch in channels:
+            ch_id = ch.get("id", "")
+            if ch_id:
+                self._last_timestamps[ch_id] = now_ts
+
+    async def _poll_channels(self) -> None:
+        channels = await self._get_joined_channels()
+        now_ts = f"{time.time():.6f}"
+        for ch in channels:
+            ch_id = ch.get("id", "")
+            if ch_id and ch_id not in self._last_timestamps:
+                self._last_timestamps[ch_id] = now_ts
+
+        for ch_id, oldest_ts in list(self._last_timestamps.items()):
+            try:
+                data = await _slack_acall(
+                    "GET", "conversations.history", self._headers(),
+                    params={"channel": ch_id, "oldest": oldest_ts, "limit": 50},
+                )
+                if "error" in data:
+                    err_code = (data.get("details") or {}).get("error", "")
+                    if err_code in ("channel_not_found", "not_in_channel"):
+                        self._last_timestamps.pop(ch_id, None)
+                    continue
+
+                messages = data.get("messages", [])
+                if not messages:
+                    continue
+
+                messages.sort(key=lambda m: float(m.get("ts", "0")))
+                for msg in messages:
+                    await self._process_message(msg, ch_id)
+                self._last_timestamps[ch_id] = messages[-1].get("ts", oldest_ts)
+            except Exception as e:
+                logger.debug(f"[SLACK] Error polling channel {ch_id}: {e}")
+
+    async def _process_message(self, msg: Dict[str, Any], channel_id: str) -> None:
+        if msg.get("bot_id") or msg.get("subtype"):
+            return
+        user_id = msg.get("user", "")
+        text = msg.get("text", "")
+        if not text or user_id == self._bot_user_id:
+            return
+
+        sender_name = user_id
+        try:
+            info = self.get_user_info(user_id)
+            if info.get("ok"):
+                profile = info.get("user", {}).get("profile", {})
+                sender_name = profile.get("display_name") or profile.get("real_name") or user_id
+        except Exception:
+            pass
+
+        ts_float = float(msg.get("ts", "0"))
+        timestamp = datetime.fromtimestamp(ts_float, tz=timezone.utc) if ts_float else None
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=user_id,
+                sender_name=sender_name,
+                text=text,
+                channel_id=channel_id,
+                message_id=msg.get("ts", ""),
+                timestamp=timestamp,
+                raw=msg,
+            ))
+
+    # ----- API -----
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"channel": recipient, "text": text}
+        if kwargs.get("thread_ts"):
+            payload["thread_ts"] = kwargs["thread_ts"]
+        if kwargs.get("blocks"):
+            payload["blocks"] = kwargs["blocks"]
+        return _slack_call("POST", "chat.postMessage", self._headers(), json=payload)
+
+    def list_channels(self, types: str = "public_channel,private_channel",
+                      limit: int = 100, exclude_archived: bool = True) -> Dict[str, Any]:
+        return _slack_call("GET", "conversations.list", self._headers(),
+                           params={"types": types, "limit": limit, "exclude_archived": exclude_archived})
+
+    def get_channel_info(self, channel: str) -> Dict[str, Any]:
+        return _slack_call("GET", "conversations.info", self._headers(), params={"channel": channel})
+
+    def get_channel_history(self, channel: str, limit: int = 100,
+                             oldest: Optional[str] = None, latest: Optional[str] = None) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"channel": channel, "limit": limit}
+        if oldest:
+            params["oldest"] = oldest
+        if latest:
+            params["latest"] = latest
+        return _slack_call("GET", "conversations.history", self._headers(), params=params)
+
+    def create_channel(self, name: str, is_private: bool = False) -> Dict[str, Any]:
+        return _slack_call("POST", "conversations.create", self._headers(),
+                           json={"name": name, "is_private": is_private})
+
+    def invite_to_channel(self, channel: str, users: List[str]) -> Dict[str, Any]:
+        return _slack_call("POST", "conversations.invite", self._headers(),
+                           json={"channel": channel, "users": ",".join(users)})
+
+    def list_users(self, limit: int = 100) -> Dict[str, Any]:
+        return _slack_call("GET", "users.list", self._headers(), params={"limit": limit})
+
+    def get_user_info(self, user_id: str) -> Dict[str, Any]:
+        return _slack_call("GET", "users.info", self._headers(), params={"user": user_id})
+
+    def open_dm(self, users: List[str]) -> Dict[str, Any]:
+        return _slack_call("POST", "conversations.open", self._headers(),
+                           json={"users": ",".join(users)})
+
+    def search_messages(self, query: str, count: int = 20, sort: str = "timestamp",
+                        sort_dir: str = "desc") -> Dict[str, Any]:
+        return _slack_call("GET", "search.messages", self._headers(),
+                           params={"query": query, "count": count, "sort": sort, "sort_dir": sort_dir})
+
+    def upload_file(self, channels: List[str], content: Optional[str] = None,
+                    file_path: Optional[str] = None, filename: Optional[str] = None,
+                    title: Optional[str] = None, initial_comment: Optional[str] = None) -> Dict[str, Any]:
+        cred = self._load()
+        form_data: Dict[str, Any] = {"channels": ",".join(channels)}
+        if filename:
+            form_data["filename"] = filename
+        if title:
+            form_data["title"] = title
+        if initial_comment:
+            form_data["initial_comment"] = initial_comment
+        files = None
+        if file_path:
+            files = {"file": open(file_path, "rb")}
+        elif content:
+            form_data["content"] = content
+        try:
+            return _slack_call("POST", "files.upload",
+                               {"Authorization": f"Bearer {cred.bot_token}"},
+                               data=form_data, files=files)
+        finally:
+            if files:
+                files["file"].close()
diff --git a/craftos_integrations/integrations/telegram_bot/INTEGRATION.md b/craftos_integrations/integrations/telegram_bot/INTEGRATION.md
new file mode 100644
index 00000000..f5a0db3b
--- /dev/null
+++ b/craftos_integrations/integrations/telegram_bot/INTEGRATION.md
@@ -0,0 +1,11 @@
+# Telegram Bot — Integration Reference
+
+Bot-token integration (the `@BotFather` flow). Sends and reads via a Telegram bot account. Distinct from `telegram_user`, which is an MTProto user-session integration.
+
+## Essentials
+
+- **No "self" alias.** Bots don't have a personal inbox. Send-to-self has no shortcut here — the agent must target a chat by `chat_id`. If the user says "message me on Telegram", they probably mean `telegram_user`, not this one.
+- **Identity formats:** `chat_id` is numeric (e.g. `123456789`, negative for groups/supergroups/channels) OR `@username` (Telegram resolves server-side). Don't pass display names.
+- **The bot must already be in the chat.** A bot cannot DM a user that hasn't first sent `/start` to it. Common error: `chat not found` when the target user hasn't initiated. Surface that to the user — retrying won't fix it.
+- **Session-level facts the integration knows:** `bot_username` (resolved at login). Use `get_telegram_bot_info` rather than asking the user.
+- **`self_messages_only` config flag:** when True, the listener drops everything except 1:1 private DMs (filters out groups/supergroups). Affects what the agent *sees* on incoming events; doesn't change sending.
diff --git a/craftos_integrations/integrations/telegram_bot/__init__.py b/craftos_integrations/integrations/telegram_bot/__init__.py
new file mode 100644
index 00000000..9a625909
--- /dev/null
+++ b/craftos_integrations/integrations/telegram_bot/__init__.py
@@ -0,0 +1,461 @@
+# -*- coding: utf-8 -*-
+"""Telegram Bot integration - handler (token + invite via shared bot) + client (long-polling)."""
+from __future__ import annotations
+
+import asyncio
+import webbrowser
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import httpx
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...config import ConfigStore
+from ...helpers import arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+TELEGRAM_API_BASE = "https://api.telegram.org"
+POLL_TIMEOUT = 30
+RETRY_DELAY = 5
+
+
+def _shape_telegram(result: Dict[str, Any]) -> Dict[str, Any]:
+    if "error" in result:
+        return result
+    data = result["result"]
+    if not data.get("ok"):
+        return {"error": data.get("description", "Unknown error"), "details": data}
+    return data
+
+
+async def _telegram_acall(url: str, *, json: Optional[Dict[str, Any]] = None,
+                          params: Optional[Dict[str, Any]] = None,
+                          timeout: float = 10.0) -> Dict[str, Any]:
+    """Telegram Bot API call. Returns raw response on ``ok=True``, ``{error, details}`` otherwise.
+
+    Layers on top of ``arequest`` to add Telegram's ``{ok: bool, result, description}`` envelope.
+    """
+    method = "POST" if json is not None else "GET"
+    result = await arequest(method, url, json=json, params=params,
+                            timeout=timeout, expected=(200,))
+    return _shape_telegram(result)
+
+
+def _telegram_call_sync(url: str, *, json: Optional[Dict[str, Any]] = None,
+                        params: Optional[Dict[str, Any]] = None,
+                        timeout: float = 10.0) -> Dict[str, Any]:
+    """Sync variant - for use from login flows where async-context detection
+    can be fragile. Wrap in ``asyncio.to_thread`` from coroutines."""
+    method = "POST" if json is not None else "GET"
+    result = http_request(method, url, json=json, params=params,
+                          timeout=timeout, expected=(200,))
+    return _shape_telegram(result)
+
+
+@dataclass
+class TelegramBotCredential:
+    bot_token: str = ""
+    bot_username: str = ""
+
+
+@dataclass
+class TelegramBotConfig:
+    """Runtime knobs persisted to ``telegram_bot_config.json``."""
+    # When True, only forward messages from private 1:1 DMs (drops groups,
+    # supergroups, and channels). Closest analog to "self-only" for a bot,
+    # which has no self-chat concept of its own.
+    self_messages_only: bool = False
+
+
+TELEGRAM_BOT = IntegrationSpec(
+    name="telegram_bot",
+    cred_class=TelegramBotCredential,
+    cred_file="telegram_bot.json",
+    platform_id="telegram_bot",
+)
+
+
+def _telegram_bot_config_file() -> str:
+    """``telegram_bot.json`` → ``telegram_bot_config.json``."""
+    stem = TELEGRAM_BOT.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(TELEGRAM_BOT.name)
+class TelegramBotHandler(IntegrationHandler):
+    spec = TELEGRAM_BOT
+    display_name = "Telegram Bot"
+    description = "Bot API messaging"
+    auth_type = "token"
+    icon = "telegram"
+    connect_help = [
+        "Open Telegram and search for @BotFather",
+        "Send /newbot and follow the prompts (pick a name, pick a username ending in 'bot')",
+        "BotFather replies with a token - copy the long string (numbers:letters)",
+        "Paste it as the Bot Token below",
+    ]
+    fields = [
+        {"key": "bot_token", "label": "Bot Token", "placeholder": "From @BotFather", "password": True},
+    ]
+
+    config_class = TelegramBotConfig
+    config_fields = [
+        {"key": "self_messages_only", "label": "Private DMs only", "type": "checkbox",
+         "help": "Only forward messages from 1:1 private chats with the bot. "
+                 "Drops group, supergroup, and channel messages before they reach the agent."},
+    ]
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["invite", "login", "logout", "status"]
+
+    async def invite(self, args: List[str]) -> Tuple[bool, str]:
+        shared_token = ConfigStore.get_oauth("TELEGRAM_SHARED_BOT_TOKEN")
+        shared_username = ConfigStore.get_oauth("TELEGRAM_SHARED_BOT_USERNAME")
+        if not shared_token or not shared_username:
+            return False, (
+                "Shared Telegram bot not configured. Set TELEGRAM_SHARED_BOT_TOKEN and "
+                "TELEGRAM_SHARED_BOT_USERNAME.\n"
+                "Alternatively, use /telegram_bot login <bot_token> with your own bot from @BotFather."
+            )
+
+        data = await asyncio.to_thread(
+            _telegram_call_sync, f"{TELEGRAM_API_BASE}/bot{shared_token}/getMe",
+        )
+        if "error" in data:
+            return False, f"Shared bot token invalid: {data['error']}"
+        info = data["result"]
+
+        save_credential(self.spec.cred_file, TelegramBotCredential(
+            bot_token=shared_token, bot_username=info.get("username", ""),
+        ))
+
+        bot_link = f"https://t.me/{shared_username}"
+        try:
+            webbrowser.open(bot_link)
+        except Exception:
+            pass
+        return True, (
+            f"Shared Telegram bot connected: @{info.get('username')}\n"
+            f"Start chatting or add to groups: {bot_link}"
+        )
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, "Usage: /telegram_bot login <bot_token>\nGet from @BotFather on Telegram."
+        bot_token = args[0]
+
+        data = await asyncio.to_thread(
+            _telegram_call_sync, f"{TELEGRAM_API_BASE}/bot{bot_token}/getMe",
+        )
+        if "error" in data:
+            return False, f"Invalid bot token: {data['error']}"
+        info = data["result"]
+
+        save_credential(self.spec.cred_file, TelegramBotCredential(
+            bot_token=bot_token, bot_username=info.get("username", ""),
+        ))
+        return True, f"Telegram bot connected: @{info.get('username')} ({info.get('id')})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Telegram bot credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Telegram bot credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Telegram bot: Not connected"
+        cred = load_credential(self.spec.cred_file, TelegramBotCredential)
+        label = f"@{cred.bot_username}" if cred and cred.bot_username else "Bot configured"
+        return True, f"Telegram bot: Connected\n  - {label}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class TelegramBotClient(BasePlatformClient):
+    spec = TELEGRAM_BOT
+    PLATFORM_ID = TELEGRAM_BOT.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[TelegramBotCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._poll_offset: int = 0
+        self._bot_info: Optional[Dict[str, Any]] = None
+        self._catchup_done: bool = False
+
+    def has_credentials(self) -> bool:
+        if has_credential(self.spec.cred_file):
+            return True
+        # Auto-save shared bot credentials from configured env if available
+        try:
+            shared_token = ConfigStore.get_oauth("TELEGRAM_SHARED_BOT_TOKEN")
+            shared_username = ConfigStore.get_oauth("TELEGRAM_SHARED_BOT_USERNAME")
+            if shared_token:
+                save_credential(self.spec.cred_file, TelegramBotCredential(
+                    bot_token=shared_token, bot_username=shared_username or "",
+                ))
+                logger.info("[TELEGRAM_BOT] Auto-saved shared bot credentials")
+                return True
+        except Exception:
+            pass
+        return False
+
+    def _load(self) -> TelegramBotCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, TelegramBotCredential)
+        if self._cred is None:
+            raise RuntimeError("No Telegram Bot credentials. Use /telegram_bot login first.")
+        return self._cred
+
+    def _api_url(self, method: str) -> str:
+        cred = self._load()
+        return f"{TELEGRAM_API_BASE}/bot{cred.bot_token}/{method}"
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"chat_id": recipient, "text": text}
+        if kwargs.get("parse_mode"):
+            payload["parse_mode"] = kwargs["parse_mode"]
+        if kwargs.get("reply_to_message_id"):
+            payload["reply_to_message_id"] = kwargs["reply_to_message_id"]
+        if kwargs.get("disable_notification"):
+            payload["disable_notification"] = True
+        return await _telegram_acall(self._api_url("sendMessage"), json=payload)
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+
+        info = await self.get_me()
+        if "error" in info:
+            raise RuntimeError(f"Invalid bot token: {info.get('error', 'unknown error')}")
+        self._bot_info = info.get("result", {})
+
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    async def _poll_loop(self) -> None:
+        try:
+            catchup_resp = await self._poll_updates()
+            for update in catchup_resp.get("result", []):
+                self._poll_offset = update.get("update_id", 0) + 1
+            self._catchup_done = True
+        except Exception as e:
+            logger.error(f"[TELEGRAM_BOT] Catchup error: {e}")
+            self._catchup_done = True
+
+        while self._listening:
+            try:
+                resp = await self._poll_updates()
+                for update in resp.get("result", []):
+                    await self._process_update(update)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[TELEGRAM_BOT] Poll error: {e}")
+                await asyncio.sleep(RETRY_DELAY)
+
+    def _poll_updates_sync(self) -> Dict[str, Any]:
+        """Sync long-poll - runs in a worker thread to bypass anyio."""
+        try:
+            resp = httpx.get(self._api_url("getUpdates"), params={
+                "offset": self._poll_offset,
+                "timeout": POLL_TIMEOUT,
+                "allowed_updates": ["message"],
+            }, timeout=POLL_TIMEOUT + 10)
+            data = resp.json()
+            return data if data.get("ok") else {"result": []}
+        except httpx.TimeoutException:
+            return {"result": []}
+
+    async def _poll_updates(self) -> Dict[str, Any]:
+        return await asyncio.to_thread(self._poll_updates_sync)
+
+    async def _process_update(self, update: Dict[str, Any]) -> None:
+        self._poll_offset = update.get("update_id", 0) + 1
+        message = update.get("message")
+        if not message:
+            return
+        text = message.get("text", "")
+        if not text:
+            return
+
+        from_user = message.get("from", {})
+        chat = message.get("chat", {})
+
+        cfg = load_config(_telegram_bot_config_file(), TelegramBotConfig) or TelegramBotConfig()
+        if cfg.self_messages_only and chat.get("type") != "private":
+            return
+
+        sender_name = from_user.get("first_name", "")
+        if from_user.get("last_name"):
+            sender_name += f" {from_user['last_name']}"
+        if from_user.get("username"):
+            sender_name += f" (@{from_user['username']})"
+
+        ts = None
+        try:
+            ts = datetime.fromtimestamp(message["date"], tz=timezone.utc)
+        except Exception:
+            pass
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=str(from_user.get("id", "")),
+                sender_name=sender_name or str(from_user.get("id", "unknown")),
+                text=text,
+                channel_id=str(chat.get("id", "")),
+                channel_name=chat.get("title", chat.get("first_name", "")),
+                message_id=str(message.get("message_id", "")),
+                timestamp=ts,
+                raw=update,
+            ))
+
+    # ----- API -----
+    async def get_me(self) -> Dict[str, Any]:
+        return await _telegram_acall(self._api_url("getMe"))
+
+    async def send_photo(self, chat_id: Union[int, str], photo: str,
+                         caption: Optional[str] = None, parse_mode: Optional[str] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"chat_id": chat_id, "photo": photo}
+        if caption:
+            payload["caption"] = caption
+        if parse_mode:
+            payload["parse_mode"] = parse_mode
+        return await _telegram_acall(self._api_url("sendPhoto"), json=payload)
+
+    async def send_document(self, chat_id: Union[int, str], document: str,
+                            caption: Optional[str] = None, parse_mode: Optional[str] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"chat_id": chat_id, "document": document}
+        if caption:
+            payload["caption"] = caption
+        if parse_mode:
+            payload["parse_mode"] = parse_mode
+        return await _telegram_acall(self._api_url("sendDocument"), json=payload)
+
+    async def get_updates(self, offset: Optional[int] = None, limit: int = 100,
+                          timeout: int = 0, allowed_updates: Optional[List[str]] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"limit": limit, "timeout": timeout}
+        if offset is not None:
+            payload["offset"] = offset
+        if allowed_updates:
+            payload["allowed_updates"] = allowed_updates
+        return await _telegram_acall(self._api_url("getUpdates"), json=payload, timeout=timeout + 10)
+
+    async def get_chat(self, chat_id: Union[int, str]) -> Dict[str, Any]:
+        return await _telegram_acall(self._api_url("getChat"), json={"chat_id": chat_id})
+
+    async def get_chat_member(self, chat_id: Union[int, str], user_id: int) -> Dict[str, Any]:
+        return await _telegram_acall(self._api_url("getChatMember"),
+                                      json={"chat_id": chat_id, "user_id": user_id})
+
+    async def get_chat_members_count(self, chat_id: Union[int, str]) -> Dict[str, Any]:
+        return await _telegram_acall(self._api_url("getChatMembersCount"), json={"chat_id": chat_id})
+
+    async def forward_message(self, chat_id: Union[int, str], from_chat_id: Union[int, str],
+                              message_id: int, disable_notification: bool = False) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"chat_id": chat_id, "from_chat_id": from_chat_id, "message_id": message_id}
+        if disable_notification:
+            payload["disable_notification"] = True
+        return await _telegram_acall(self._api_url("forwardMessage"), json=payload)
+
+    async def search_contact(self, name: str) -> Dict[str, Any]:
+        updates_result = await self.get_updates(limit=100)
+        if "error" in updates_result:
+            return updates_result
+
+        seen_ids: set = set()
+        contacts: List[Dict[str, Any]] = []
+        search_lower = name.lower()
+        updates = updates_result.get("result", [])
+
+        for update in updates:
+            message = update.get("message") or update.get("edited_message")
+            if not message:
+                continue
+            chat = message.get("chat", {})
+            chat_id = chat.get("id")
+            if chat_id and chat_id not in seen_ids:
+                seen_ids.add(chat_id)
+                chat_type = chat.get("type", "")
+                if chat_type == "private":
+                    full_name = f"{chat.get('first_name', '')} {chat.get('last_name', '')}".strip()
+                    searchable = f"{full_name} {chat.get('username', '')}".lower()
+                else:
+                    full_name = chat.get("title", "")
+                    searchable = f"{full_name} {chat.get('username', '')}".lower()
+                if search_lower in searchable:
+                    contacts.append({
+                        "chat_id": chat_id, "type": chat_type, "name": full_name or chat.get("username", ""),
+                        "username": chat.get("username", ""),
+                        "first_name": chat.get("first_name", ""), "last_name": chat.get("last_name", ""),
+                    })
+            sender = message.get("from", {})
+            sender_id = sender.get("id")
+            if sender_id and sender_id not in seen_ids:
+                seen_ids.add(sender_id)
+                full_name = f"{sender.get('first_name', '')} {sender.get('last_name', '')}".strip()
+                searchable = f"{full_name} {sender.get('username', '')}".lower()
+                if search_lower in searchable and not sender.get("is_bot"):
+                    contacts.append({
+                        "chat_id": sender_id, "type": "private",
+                        "name": full_name or sender.get("username", ""), "username": sender.get("username", ""),
+                        "first_name": sender.get("first_name", ""), "last_name": sender.get("last_name", ""),
+                    })
+
+        if contacts:
+            return {"ok": True, "result": {"contacts": contacts, "count": len(contacts)}}
+        return {"error": f"No contacts found matching '{name}'",
+                "details": {"searched_updates": len(updates), "name": name}}
diff --git a/craftos_integrations/integrations/telegram_user/INTEGRATION.md b/craftos_integrations/integrations/telegram_user/INTEGRATION.md
new file mode 100644
index 00000000..c75fc150
--- /dev/null
+++ b/craftos_integrations/integrations/telegram_user/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Telegram User — Integration Reference
+
+MTProto user-session integration — the agent acts AS the user's own Telegram account (not as a bot). Useful when the user wants the agent to send messages on their behalf from their personal account.
+
+## Essentials
+
+- **Self-send shortcut:** `chat_id="user"` (also `"me"`, `"self"`, `"owner"`) is auto-resolved to the user's own Telegram user ID and routes to Saved Messages (Telegram's personal note-to-self channel). Never ask the user for their own Telegram ID — call `get_telegram_user_account_info` if you need it.
+- **Identity formats:** numeric user/chat IDs (negative for groups/channels) or `@username`. Display names are not resolvable — search via `search_telegram_user_contacts` if you only have a name.
+- **Session-level facts the integration knows:** the user's `phone_number` and `user_id`. Look up rather than asking.
+- **Outgoing messages are auto-prefixed with `[AGENT_NAME]`** so the agent can filter its own echoes out of Saved Messages on receive. Don't add the prefix yourself.
+- **Session expiry:** the MTProto session can be revoked from another device — surfaces as `AuthKeyUnregisteredError`. Tell the user to reconnect; do NOT retry.
+- **Flood waits:** `FloodWaitError` carries the required retry-after seconds. Respect it; don't hammer the API.
diff --git a/craftos_integrations/integrations/telegram_user/__init__.py b/craftos_integrations/integrations/telegram_user/__init__.py
new file mode 100644
index 00000000..d0988b34
--- /dev/null
+++ b/craftos_integrations/integrations/telegram_user/__init__.py
@@ -0,0 +1,706 @@
+# -*- coding: utf-8 -*-
+"""Telegram MTProto (user account) integration - handler (phone+code+QR) + client (Telethon listener)."""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+import webbrowser
+from dataclasses import dataclass
+from datetime import timezone
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...config import ConfigStore
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class TelegramUserCredential:
+    session_string: str = ""
+    api_id: str = ""
+    api_hash: str = ""
+    phone_number: str = ""
+
+
+@dataclass
+class TelegramUserConfig:
+    """Runtime knobs persisted to ``telegram_user_config.json``."""
+    # When True, only forward messages from the user's own Saved Messages
+    # chat (chat_id == own user_id). All DMs from contacts and group/channel
+    # chatter are dropped before reaching the agent. Useful when the user
+    # wants Telegram to act as a personal command channel only.
+    self_messages_only: bool = False
+
+
+TELEGRAM_USER = IntegrationSpec(
+    name="telegram_user",
+    cred_class=TelegramUserCredential,
+    cred_file="telegram_user.json",
+    platform_id="telegram_user",
+)
+
+
+def _telegram_user_config_file() -> str:
+    """``telegram_user.json`` → ``telegram_user_config.json``."""
+    stem = TELEGRAM_USER.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# Module-level pending auth state (mirrors original handlers.py behaviour)
+_pending_telegram_auth: Dict[str, Dict[str, Any]] = {}
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(TELEGRAM_USER.name)
+class TelegramUserHandler(IntegrationHandler):
+    spec = TELEGRAM_USER
+    display_name = "Telegram (User)"
+    description = "MTProto user account"
+    auth_type = "interactive"
+    icon = "telegram"
+    connect_help = [
+        "Open my.telegram.org and log in with your Telegram phone number",
+        "Click 'API development tools'",
+        "Fill the form (any app name/short name works) and submit",
+        "Copy the 'api_id' (number) and 'api_hash' (long hex string)",
+        "Set them as TELEGRAM_API_ID and TELEGRAM_API_HASH in CraftBot config",
+        "Then click Connect - you'll be prompted for your phone + login code",
+    ]
+    fields: List = []
+
+    config_class = TelegramUserConfig
+    config_fields = [
+        {"key": "self_messages_only", "label": "Self-messages only", "type": "checkbox",
+         "help": "Only forward messages from your own Saved Messages chat. "
+                 "Drops DMs from contacts and group/channel messages before they reach the agent."},
+    ]
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["login", "login-qr", "logout", "status"]
+
+    async def handle(self, sub: str, args: List[str]) -> Tuple[bool, str]:
+        if sub == "login-qr":
+            return await self._login_qr(args)
+        if sub == "login":
+            # Two-step: phone (+code) flow
+            return await self._login_phone(args)
+        return await super().handle(sub, args)
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        return await self._login_phone(args)
+
+    async def _login_phone(self, args: List[str]) -> Tuple[bool, str]:
+        if not args:
+            return False, (
+                "Usage:\n"
+                "  Step 1: /telegram_user login <phone_number>\n"
+                "  Step 2: /telegram_user login <phone_number> <code> [2fa_password]\n\n"
+                "Requires TELEGRAM_API_ID and TELEGRAM_API_HASH env vars or configure(oauth=...).\n"
+                "Get them from https://my.telegram.org"
+            )
+
+        phone = args[0]
+        api_id_str = ConfigStore.get_oauth("TELEGRAM_API_ID")
+        api_hash = ConfigStore.get_oauth("TELEGRAM_API_HASH")
+        if not api_id_str or not api_hash:
+            return False, (
+                "Not configured. Set TELEGRAM_API_ID and TELEGRAM_API_HASH.\n"
+                "Get them from https://my.telegram.org → API development tools."
+            )
+        try:
+            api_id = int(api_id_str)
+        except ValueError:
+            return False, "TELEGRAM_API_ID must be a number."
+
+        from . import _telegram_mtproto as helpers
+
+        # Step 2: phone + code → complete
+        if len(args) >= 2:
+            code = args[1]
+            password = args[2] if len(args) > 2 else None
+
+            pending = _pending_telegram_auth.get(phone)
+            if not pending:
+                return False, f"No pending auth for {phone}. Run /telegram_user login {phone} first."
+
+            result = await helpers.complete_auth(
+                api_id=api_id, api_hash=api_hash,
+                phone_number=phone, code=code,
+                phone_code_hash=pending["phone_code_hash"],
+                password=password,
+                pending_session_string=pending["session_string"],
+            )
+
+            if "error" in result:
+                details = result.get("details", {})
+                if details.get("status") == "2fa_required":
+                    return False, "2FA enabled.\nUsage: /telegram_user login <phone> <code> <2fa_password>"
+                if details.get("status") == "invalid_code":
+                    return False, "Invalid verification code. Try again."
+                if details.get("status") == "code_expired":
+                    _pending_telegram_auth.pop(phone, None)
+                    return False, "Code expired. Run /telegram_user login <phone> again."
+                return False, f"Auth failed: {result['error']}"
+
+            auth = result["result"]
+            _pending_telegram_auth.pop(phone, None)
+
+            save_credential(self.spec.cred_file, TelegramUserCredential(
+                session_string=auth["session_string"],
+                api_id=str(api_id),
+                api_hash=api_hash,
+                phone_number=auth.get("phone", phone),
+            ))
+
+            account_name = f"{auth.get('first_name', '')} {auth.get('last_name', '')}".strip()
+            username = f" (@{auth['username']})" if auth.get("username") else ""
+            return True, f"Telegram user connected: {account_name}{username}"
+
+        # Step 1: send OTP
+        result = await helpers.start_auth(api_id=api_id, api_hash=api_hash, phone_number=phone)
+        if "error" in result:
+            return False, f"Failed to send code: {result['error']}"
+
+        _pending_telegram_auth[phone] = {
+            "phone_code_hash": result["result"]["phone_code_hash"],
+            "session_string": result["result"]["session_string"],
+        }
+        return True, (
+            f"Verification code sent to {phone}.\n"
+            f"Check your Telegram app (or SMS) for the code, then run:\n"
+            f"  /telegram_user login {phone} <code>"
+        )
+
+    async def _login_qr(self, args: List[str]) -> Tuple[bool, str]:
+        api_id_str = ConfigStore.get_oauth("TELEGRAM_API_ID")
+        api_hash = ConfigStore.get_oauth("TELEGRAM_API_HASH")
+        if not api_id_str or not api_hash:
+            return False, "Not configured. Set TELEGRAM_API_ID and TELEGRAM_API_HASH."
+        try:
+            api_id = int(api_id_str)
+        except ValueError:
+            return False, "TELEGRAM_API_ID must be a number."
+
+        try:
+            import qrcode as _qrcode_check  # noqa: F401
+        except ImportError:
+            return False, "qrcode package not installed. Run: pip install qrcode[pil]"
+
+        qr_file_path = None
+        qr_error = None
+
+        def on_qr_url(url: str):
+            nonlocal qr_file_path, qr_error
+            try:
+                import qrcode
+                qr = qrcode.QRCode(version=1, box_size=10, border=4)
+                qr.add_data(url)
+                qr.make(fit=True)
+                img = qr.make_image(fill_color="black", back_color="white")
+                qr_file_path = os.path.join(tempfile.gettempdir(), "telegram_qr_login.png")
+                img.save(qr_file_path)
+                if sys.platform == "win32":
+                    os.startfile(qr_file_path)
+                else:
+                    webbrowser.open(f"file://{qr_file_path}")
+            except Exception as e:
+                qr_error = str(e)
+
+        from . import _telegram_mtproto as helpers
+        result = await helpers.qr_login(
+            api_id=api_id, api_hash=api_hash,
+            on_qr_url=on_qr_url, timeout=120,
+        )
+
+        if qr_file_path and os.path.exists(qr_file_path):
+            try:
+                os.remove(qr_file_path)
+            except Exception:
+                pass
+
+        if "error" in result:
+            details = result.get("details", {})
+            if details.get("status") == "2fa_required":
+                session_str = details.get("session_string", "")
+                if session_str:
+                    _pending_telegram_auth["__qr_2fa__"] = {"session_string": session_str}
+                return False, (
+                    "QR scan succeeded but 2FA is enabled.\n"
+                    "Complete login with: /telegram_user login <phone> <code> <2fa_password>"
+                )
+            return False, f"QR login failed: {result['error']}"
+
+        auth = result["result"]
+        save_credential(self.spec.cred_file, TelegramUserCredential(
+            session_string=auth["session_string"],
+            api_id=str(api_id),
+            api_hash=api_hash,
+            phone_number=auth.get("phone", ""),
+        ))
+        account_name = f"{auth.get('first_name', '')} {auth.get('last_name', '')}".strip()
+        username = f" (@{auth['username']})" if auth.get("username") else ""
+        return True, f"Telegram user linked: {account_name}{username}"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Telegram user credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Telegram user credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Telegram user: Not connected"
+        cred = load_credential(self.spec.cred_file, TelegramUserCredential)
+        label = cred.phone_number if cred and cred.phone_number else "User configured"
+        return True, f"Telegram user: Connected\n  - {label}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class TelegramUserClient(BasePlatformClient):
+    spec = TELEGRAM_USER
+    PLATFORM_ID = TELEGRAM_USER.platform_id
+
+    _OWNER_ALIASES = {"user", "owner", "me", "self"}
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[TelegramUserCredential] = None
+        self._live_client = None
+        self._live_loop = None
+        self._send_queue: Optional[asyncio.Queue] = None
+        self._send_task = None
+        self._my_user_id: Optional[int] = None
+        self._agent_sent_ids: set = set()
+
+    def _resolve_recipient(self, recipient: str) -> str:
+        if recipient.strip().lower() in self._OWNER_ALIASES:
+            if self._my_user_id:
+                return str(self._my_user_id)
+            return "me"
+        return recipient
+
+    @property
+    def _agent_prefix(self) -> str:
+        name = ConfigStore.extras.get("agent_name", "AGENT")
+        return f"[{name}] "
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> TelegramUserCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, TelegramUserCredential)
+        if self._cred is None:
+            raise RuntimeError("No Telegram User credentials. Use /telegram_user login first.")
+        return self._cred
+
+    def _session_params(self):
+        from telethon.sessions import StringSession
+        cred = self._load()
+        return StringSession(cred.session_string), int(cred.api_id), cred.api_hash
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+
+        try:
+            from telethon import TelegramClient, events
+        except ImportError:
+            raise RuntimeError("telethon is not installed")
+
+        session, api_id, api_hash = self._session_params()
+        client = TelegramClient(session, api_id, api_hash)
+        await client.connect()
+        self._live_loop = asyncio.get_event_loop()
+
+        if not await client.is_user_authorized():
+            await client.disconnect()
+            raise RuntimeError("Telegram user session expired or revoked. Please re-authenticate.")
+
+        me = await client.get_me()
+        self._my_user_id = me.id
+        self._live_client = client
+
+        @client.on(events.NewMessage)
+        async def _on_new_message(event):
+            try:
+                await self._handle_event(event)
+            except Exception as e:
+                logger.error(f"[TELEGRAM_USER] Error handling message event: {e}")
+
+        await client.catch_up()
+        self._send_queue = asyncio.Queue()
+
+        async def _send_processor():
+            while self._listening:
+                try:
+                    item = await asyncio.wait_for(self._send_queue.get(), timeout=60)
+                    recipient, text, reply_to, result_future = item
+                    try:
+                        try:
+                            entity = await client.get_entity(int(recipient) if recipient.lstrip('-').isdigit() else recipient)
+                        except ValueError:
+                            entity = await client.get_entity(recipient)
+                        msg = await client.send_message(entity, text, reply_to=reply_to)
+                        result_future.set_result(msg)
+                    except Exception as e:
+                        result_future.set_exception(e)
+                except asyncio.TimeoutError:
+                    try:
+                        if self._live_client and self._live_client.is_connected():
+                            await self._live_client.catch_up()
+                    except Exception:
+                        pass
+                except asyncio.CancelledError:
+                    break
+                except Exception:
+                    pass
+        self._send_task = asyncio.create_task(_send_processor())
+        self._listening = True
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        for task in [getattr(self, "_run_task", None), getattr(self, "_send_task", None)]:
+            if task and not task.done():
+                task.cancel()
+        self._run_task = None
+        self._send_task = None
+        self._send_queue = None
+        if self._live_client:
+            try:
+                await self._live_client.disconnect()
+            except Exception:
+                pass
+            self._live_client = None
+
+    async def _handle_event(self, event) -> None:
+        msg = event.message
+        if not msg or not msg.text:
+            return
+        chat_id = event.chat_id
+        is_saved_messages = (chat_id == self._my_user_id)
+
+        cfg = load_config(_telegram_user_config_file(), TelegramUserConfig) or TelegramUserConfig()
+        if cfg.self_messages_only and not is_saved_messages:
+            return
+
+        if msg.out and not is_saved_messages:
+            return
+
+        if is_saved_messages and msg.out:
+            msg_id_str = str(msg.id)
+            if msg_id_str in self._agent_sent_ids:
+                self._agent_sent_ids.discard(msg_id_str)
+                return
+            if msg.text.startswith(self._agent_prefix):
+                return
+
+        sender = await event.get_sender()
+        chat = await event.get_chat()
+        sender_name = _get_display_name(sender) if sender else "Unknown"
+        channel_name = _get_display_name(chat) if chat else ""
+
+        if self._message_callback:
+            await self._message_callback(PlatformMessage(
+                platform=self.spec.platform_id,
+                sender_id=str(sender.id if sender else self._my_user_id),
+                sender_name=sender_name,
+                text=msg.text,
+                channel_id=str(chat_id),
+                channel_name=channel_name if not is_saved_messages else "Saved Messages",
+                message_id=str(msg.id),
+                timestamp=msg.date.astimezone(timezone.utc) if msg.date else None,
+                raw={"is_self_message": is_saved_messages},
+            ))
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+        reply_to: Optional[int] = kwargs.get("reply_to")
+        resolved = self._resolve_recipient(recipient)
+        prefixed_text = f"{self._agent_prefix}{text}"
+
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError, FloodWaitError
+
+            if self._send_queue is not None and self._live_client and self._live_client.is_connected():
+                loop = asyncio.get_event_loop()
+                result_future = loop.create_future()
+                await self._send_queue.put((resolved, prefixed_text, reply_to, result_future))
+                msg = await asyncio.wait_for(result_future, timeout=30)
+            else:
+                session, api_id, api_hash = self._session_params()
+                async with TelegramClient(session, api_id, api_hash) as client:
+                    try:
+                        entity = await client.get_entity(int(resolved) if resolved.lstrip('-').isdigit() else resolved)
+                    except ValueError:
+                        entity = await client.get_entity(resolved)
+                    msg = await client.send_message(entity, prefixed_text, reply_to=reply_to)
+
+                self._agent_sent_ids.add(str(msg.id))
+                return {"ok": True, "result": {
+                    "message_id": msg.id,
+                    "date": msg.date.isoformat() if msg.date else None,
+                    "chat_id": getattr(msg, "chat_id", None) or resolved,
+                    "text": msg.text,
+                }}
+
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session has expired or been revoked. Please re-authenticate.",
+                    "details": {"status": "session_expired"}}
+        except ValueError as e:
+            return {"error": f"Could not find chat: {e}", "details": {"chat_id": str(recipient)}}
+        except FloodWaitError as e:
+            return {"error": f"Rate limited. Please wait {e.seconds} seconds.",
+                    "details": {"flood_wait_seconds": e.seconds}}
+        except Exception as e:
+            return {"error": f"Failed to send message: {e}", "details": {"exception": type(e).__name__}}
+
+    # --- API methods ---
+    async def get_me(self) -> Dict[str, Any]:
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError
+            session, api_id, api_hash = self._session_params()
+            async with TelegramClient(session, api_id, api_hash) as client:
+                me = await client.get_me()
+                return {"ok": True, "result": {
+                    "user_id": me.id, "first_name": me.first_name or "",
+                    "last_name": me.last_name or "", "username": me.username or "",
+                    "phone": me.phone or "", "is_bot": me.bot,
+                }}
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session expired. Please re-authenticate.",
+                    "details": {"status": "session_expired"}}
+        except Exception as e:
+            return {"error": f"Failed to get user info: {e}",
+                    "details": {"exception": type(e).__name__}}
+
+    async def get_dialogs(self, limit: int = 50) -> Dict[str, Any]:
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError
+            from telethon.tl.types import User, Chat, Channel
+            session, api_id, api_hash = self._session_params()
+            async with TelegramClient(session, api_id, api_hash) as client:
+                dialogs = await client.get_dialogs(limit=limit)
+                result = []
+                for dialog in dialogs:
+                    entity = dialog.entity
+                    info: Dict[str, Any] = {
+                        "id": dialog.id, "name": dialog.name or "",
+                        "unread_count": dialog.unread_count, "is_pinned": dialog.pinned,
+                        "is_archived": dialog.archived,
+                    }
+                    if isinstance(entity, User):
+                        info.update({"type": "private", "username": entity.username or "",
+                                     "phone": entity.phone or "", "is_bot": entity.bot})
+                    elif isinstance(entity, Chat):
+                        info.update({"type": "group",
+                                     "participants_count": getattr(entity, "participants_count", None)})
+                    elif isinstance(entity, Channel):
+                        info.update({"type": "channel" if entity.broadcast else "supergroup",
+                                     "username": entity.username or "",
+                                     "participants_count": getattr(entity, "participants_count", None)})
+                    else:
+                        info["type"] = "unknown"
+                    if dialog.message:
+                        info["last_message"] = {
+                            "id": dialog.message.id,
+                            "date": dialog.message.date.isoformat() if dialog.message.date else None,
+                            "text": dialog.message.text[:100] if dialog.message.text else "",
+                        }
+                    result.append(info)
+                return {"ok": True, "result": {"dialogs": result, "count": len(result)}}
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session expired.", "details": {"status": "session_expired"}}
+        except Exception as e:
+            return {"error": f"Failed to get dialogs: {e}", "details": {"exception": type(e).__name__}}
+
+    async def get_messages(self, chat_id: Union[int, str], limit: int = 50,
+                           offset_id: int = 0) -> Dict[str, Any]:
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError
+            session, api_id, api_hash = self._session_params()
+            async with TelegramClient(session, api_id, api_hash) as client:
+                entity = await client.get_entity(chat_id)
+                messages = await client.get_messages(entity, limit=limit, offset_id=offset_id)
+                result = []
+                for msg in messages:
+                    info: Dict[str, Any] = {
+                        "id": msg.id,
+                        "date": msg.date.isoformat() if msg.date else None,
+                        "text": msg.text or "", "out": msg.out,
+                    }
+                    if msg.sender:
+                        info["sender"] = {
+                            "id": msg.sender.id, "name": _get_display_name(msg.sender),
+                            "username": getattr(msg.sender, "username", None) or "",
+                        }
+                    if msg.media:
+                        info["has_media"] = True
+                        info["media_type"] = type(msg.media).__name__
+                    if msg.reply_to:
+                        info["reply_to_msg_id"] = msg.reply_to.reply_to_msg_id
+                    if msg.forward:
+                        info["is_forwarded"] = True
+                    result.append(info)
+                return {"ok": True, "result": {
+                    "chat": {"id": entity.id, "name": _get_display_name(entity),
+                             "type": _get_entity_type(entity)},
+                    "messages": result, "count": len(result),
+                }}
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session expired.", "details": {"status": "session_expired"}}
+        except ValueError as e:
+            return {"error": f"Could not find chat: {e}", "details": {"chat_id": str(chat_id)}}
+        except Exception as e:
+            return {"error": f"Failed to get messages: {e}", "details": {"exception": type(e).__name__}}
+
+    async def send_file(self, chat_id: Union[int, str], file_path: str,
+                        caption: Optional[str] = None, reply_to: Optional[int] = None) -> Dict[str, Any]:
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError, FloodWaitError
+            session, api_id, api_hash = self._session_params()
+            async with TelegramClient(session, api_id, api_hash) as client:
+                entity = await client.get_entity(chat_id)
+                msg = await client.send_file(entity, file_path, caption=caption, reply_to=reply_to)
+                return {"ok": True, "result": {
+                    "message_id": msg.id,
+                    "date": msg.date.isoformat() if msg.date else None,
+                    "chat_id": entity.id, "has_media": True,
+                }}
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session expired.", "details": {"status": "session_expired"}}
+        except ValueError as e:
+            return {"error": f"Could not find chat: {e}", "details": {"chat_id": str(chat_id)}}
+        except FileNotFoundError:
+            return {"error": f"File not found: {file_path}", "details": {"file_path": file_path}}
+        except FloodWaitError as e:
+            return {"error": f"Rate limited. Wait {e.seconds}s.",
+                    "details": {"flood_wait_seconds": e.seconds}}
+        except Exception as e:
+            return {"error": f"Failed to send file: {e}", "details": {"exception": type(e).__name__}}
+
+    async def search_contacts(self, query: str, limit: int = 20) -> Dict[str, Any]:
+        try:
+            from telethon import TelegramClient
+            from telethon.errors import AuthKeyUnregisteredError
+            from telethon.tl.types import User
+            session, api_id, api_hash = self._session_params()
+            async with TelegramClient(session, api_id, api_hash) as client:
+                dialogs = await client.get_dialogs(limit=100)
+                contacts: List[Dict[str, Any]] = []
+                query_lower = query.lower()
+                for dialog in dialogs:
+                    entity = dialog.entity
+                    name = _get_display_name(entity).lower()
+                    username = (getattr(entity, "username", "") or "").lower()
+                    if query_lower in name or query_lower in username:
+                        info: Dict[str, Any] = {
+                            "id": entity.id, "name": _get_display_name(entity),
+                            "username": getattr(entity, "username", None) or "",
+                            "type": _get_entity_type(entity),
+                        }
+                        if isinstance(entity, User):
+                            info["phone"] = entity.phone or ""
+                            info["is_bot"] = entity.bot
+                        contacts.append(info)
+                        if len(contacts) >= limit:
+                            break
+                return {"ok": True, "result": {"contacts": contacts, "count": len(contacts)}}
+        except ImportError:
+            return {"error": "telethon is not installed", "details": {}}
+        except AuthKeyUnregisteredError:
+            return {"error": "Session expired.", "details": {"status": "session_expired"}}
+        except Exception as e:
+            return {"error": f"Failed to search contacts: {e}",
+                    "details": {"exception": type(e).__name__}}
+
+
+# -----------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------
+
+def _get_display_name(entity) -> str:
+    try:
+        from telethon.tl.types import User
+    except ImportError:
+        return str(getattr(entity, "id", ""))
+    if isinstance(entity, User):
+        parts = []
+        if entity.first_name:
+            parts.append(entity.first_name)
+        if entity.last_name:
+            parts.append(entity.last_name)
+        return " ".join(parts) or entity.username or str(entity.id)
+    elif hasattr(entity, "title"):
+        return entity.title or ""
+    return str(entity.id)
+
+
+def _get_entity_type(entity) -> str:
+    try:
+        from telethon.tl.types import User, Chat, Channel
+    except ImportError:
+        return "unknown"
+    if isinstance(entity, User):
+        return "bot" if entity.bot else "user"
+    elif isinstance(entity, Chat):
+        return "group"
+    elif isinstance(entity, Channel):
+        return "channel" if entity.broadcast else "supergroup"
+    return "unknown"
diff --git a/craftos_integrations/integrations/telegram_user/_telegram_mtproto.py b/craftos_integrations/integrations/telegram_user/_telegram_mtproto.py
new file mode 100644
index 00000000..c6957367
--- /dev/null
+++ b/craftos_integrations/integrations/telegram_user/_telegram_mtproto.py
@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""Telegram MTProto auth helpers — underscore-prefixed so the autoloader skips it.
+
+Used only by the telegram_user handler for the phone-code and QR login flows.
+"""
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Any, Dict, Optional
+
+try:
+    from telethon import TelegramClient
+    from telethon.sessions import StringSession
+    from telethon.errors import (
+        FloodWaitError,
+        PasswordHashInvalidError,
+        PhoneCodeExpiredError,
+        PhoneCodeInvalidError,
+        SessionPasswordNeededError,
+    )
+    _TELETHON_AVAILABLE = True
+except ImportError:
+    _TELETHON_AVAILABLE = False
+
+_TELETHON_MISSING = {"error": "Telethon not installed. Run: pip install telethon"}
+
+
+def _unexpected(prefix: str, e: Exception) -> Dict[str, Any]:
+    return {"error": f"{prefix}: {e}", "details": {"exception": type(e).__name__}}
+
+
+@asynccontextmanager
+async def _client_for_auth(api_id: int, api_hash: str, session_string: str = ""):
+    """Connect a Telethon client and guarantee disconnect on exit (success or error)."""
+    client = TelegramClient(StringSession(session_string), api_id, api_hash)
+    await client.connect()
+    try:
+        yield client
+    finally:
+        try:
+            await client.disconnect()
+        except Exception:
+            pass
+
+
+async def start_auth(api_id: int, api_hash: str, phone_number: str) -> Dict[str, Any]:
+    if not _TELETHON_AVAILABLE:
+        return _TELETHON_MISSING
+    try:
+        async with _client_for_auth(api_id, api_hash) as client:
+            result = await client.send_code_request(phone_number)
+            return {"ok": True, "result": {
+                "phone_code_hash": result.phone_code_hash,
+                "phone_number": phone_number,
+                "session_string": client.session.save(),
+                "status": "code_sent",
+            }}
+    except FloodWaitError as e:
+        return {"error": f"Too many attempts. Please wait {e.seconds} seconds.",
+                "details": {"flood_wait_seconds": e.seconds}}
+    except Exception as e:
+        return _unexpected("Failed to start auth", e)
+
+
+async def qr_login(api_id: int, api_hash: str,
+                   on_qr_url: Optional[Any] = None,
+                   timeout: int = 120) -> Dict[str, Any]:
+    if not _TELETHON_AVAILABLE:
+        return _TELETHON_MISSING
+    try:
+        async with _client_for_auth(api_id, api_hash) as client:
+            try:
+                qr = await client.qr_login()
+                if on_qr_url:
+                    on_qr_url(qr.url)
+                try:
+                    await asyncio.wait_for(qr.wait(timeout), timeout=timeout)
+                except asyncio.TimeoutError:
+                    return {"error": "QR login timed out. Please try again.",
+                            "details": {"status": "timeout"}}
+            except SessionPasswordNeededError:
+                return {"error": "Two-factor authentication is enabled. Please provide your 2FA password.",
+                        "details": {"status": "2fa_required", "session_string": client.session.save()}}
+
+            try:
+                me = await client.get_me()
+            except Exception as e:
+                return _unexpected("QR login succeeded but failed to get user info", e)
+
+            return {"ok": True, "result": {
+                "session_string": client.session.save(),
+                "user_id": me.id,
+                "first_name": me.first_name or "",
+                "last_name": me.last_name or "",
+                "username": me.username or "",
+                "phone": me.phone or "",
+                "status": "authenticated",
+            }}
+    except Exception as e:
+        return _unexpected("QR login failed", e)
+
+
+async def complete_auth(api_id: int, api_hash: str, phone_number: str,
+                        code: str, phone_code_hash: str,
+                        password: Optional[str] = None,
+                        pending_session_string: Optional[str] = None) -> Dict[str, Any]:
+    if not _TELETHON_AVAILABLE:
+        return _TELETHON_MISSING
+    try:
+        async with _client_for_auth(api_id, api_hash, pending_session_string or "") as client:
+            try:
+                await client.sign_in(phone=phone_number, code=code, phone_code_hash=phone_code_hash)
+            except SessionPasswordNeededError:
+                if not password:
+                    return {"error": "Two-factor authentication is enabled. Please provide password.",
+                            "details": {"requires_2fa": True, "status": "2fa_required"}}
+                try:
+                    await client.sign_in(password=password)
+                except PasswordHashInvalidError:
+                    return {"error": "Invalid 2FA password.", "details": {"status": "invalid_password"}}
+
+            me = await client.get_me()
+            return {"ok": True, "result": {
+                "session_string": client.session.save(),
+                "user_id": me.id,
+                "first_name": me.first_name or "",
+                "last_name": me.last_name or "",
+                "username": me.username or "",
+                "phone": me.phone or phone_number,
+                "status": "authenticated",
+            }}
+
+    except PhoneCodeInvalidError:
+        return {"error": "Invalid verification code.", "details": {"status": "invalid_code"}}
+    except PhoneCodeExpiredError:
+        return {"error": "Verification code has expired. Please request a new one.",
+                "details": {"status": "code_expired"}}
+    except FloodWaitError as e:
+        return {"error": f"Too many attempts. Please wait {e.seconds} seconds.",
+                "details": {"flood_wait_seconds": e.seconds}}
+    except Exception as e:
+        return _unexpected("Failed to complete auth", e)
diff --git a/craftos_integrations/integrations/twitter/INTEGRATION.md b/craftos_integrations/integrations/twitter/INTEGRATION.md
new file mode 100644
index 00000000..6724ca18
--- /dev/null
+++ b/craftos_integrations/integrations/twitter/INTEGRATION.md
@@ -0,0 +1,12 @@
+# Twitter / X — Integration Reference
+
+X API v2 integration via OAuth 1.0a. Post / reply / delete tweets, search, timeline, like / retweet, and mention-polling.
+
+## Essentials
+
+- **Tweet IDs are numeric strings, not URLs or @handles.** Treat as opaque — pull from `search_tweets` / `get_twitter_timeline` results and pass through. Never construct.
+- **280-char hard limit on `post_tweet`.** No auto-truncation. >280 → API returns 400. The router must truncate (or split into a thread) before calling, not after the error.
+- **Session-level facts:** `cred.user_id` and `cred.username` are resolved at first connect and saved to the credential. Don't ask the user for their handle — read the credential.
+- **`watch_tag` config silently drops mentions.** If set, only mentions containing that tag trigger the router (the instruction is the text AFTER the tag, with leading @-mentions stripped). Empty tag = all mentions trigger.
+- **`429` rate-limit means back off, not retry.** The poller already sleeps 60s on 429. Don't add a retry loop in actions — repeated calls deepen the rate-limit window.
+- **Reply target field is `reply_to_tweet_id`, not `reply_to`.** Passing the wrong field name → reply posts as a standalone tweet to the user's feed.
diff --git a/craftos_integrations/integrations/twitter/__init__.py b/craftos_integrations/integrations/twitter/__init__.py
new file mode 100644
index 00000000..e06c59a1
--- /dev/null
+++ b/craftos_integrations/integrations/twitter/__init__.py
@@ -0,0 +1,495 @@
+# -*- coding: utf-8 -*-
+"""Twitter/X integration - handler + client + credential. OAuth 1.0a."""
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import secrets as _secrets
+import time
+import urllib.parse
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    save_config,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, arequest, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+TWITTER_API = "https://api.twitter.com/2"
+POLL_INTERVAL = 30
+RETRY_DELAY = 60
+
+
+@dataclass
+class TwitterCredential:
+    api_key: str = ""
+    api_secret: str = ""
+    access_token: str = ""
+    access_token_secret: str = ""
+    user_id: str = ""
+    username: str = ""
+
+
+@dataclass
+class TwitterConfig:
+    """Runtime knobs separate from the credential - persisted as
+    ``twitter_config.json``."""
+    watch_tag: str = ""
+
+
+TWITTER = IntegrationSpec(
+    name="twitter",
+    cred_class=TwitterCredential,
+    cred_file="twitter.json",
+    platform_id="twitter",
+)
+
+
+def _twitter_config_file() -> str:
+    """``twitter.json`` → ``twitter_config.json``."""
+    stem = TWITTER.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+def _oauth1_header(
+    method: str,
+    url: str,
+    params: Dict[str, str],
+    api_key: str,
+    api_secret: str,
+    access_token: str,
+    access_token_secret: str,
+) -> str:
+    oauth_params = {
+        "oauth_consumer_key": api_key,
+        "oauth_nonce": _secrets.token_hex(16),
+        "oauth_signature_method": "HMAC-SHA1",
+        "oauth_timestamp": str(int(time.time())),
+        "oauth_token": access_token,
+        "oauth_version": "1.0",
+    }
+    all_params = {**params, **oauth_params}
+    sorted_params = "&".join(
+        f"{urllib.parse.quote(k, safe='')}={urllib.parse.quote(v, safe='')}"
+        for k, v in sorted(all_params.items())
+    )
+    base_string = f"{method.upper()}&{urllib.parse.quote(url, safe='')}&{urllib.parse.quote(sorted_params, safe='')}"
+    signing_key = f"{urllib.parse.quote(api_secret, safe='')}&{urllib.parse.quote(access_token_secret, safe='')}"
+    signature = base64.b64encode(
+        hmac.new(signing_key.encode(), base_string.encode(), hashlib.sha1).digest()
+    ).decode()
+    oauth_params["oauth_signature"] = signature
+    header_parts = ", ".join(
+        f'{urllib.parse.quote(k, safe="")}="{urllib.parse.quote(v, safe="")}"'
+        for k, v in sorted(oauth_params.items())
+    )
+    return f"OAuth {header_parts}"
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(TWITTER.name)
+class TwitterHandler(IntegrationHandler):
+    spec = TWITTER
+    display_name = "Twitter/X"
+    description = "Tweets, mentions, and timeline"
+    auth_type = "token"
+    icon = "twitter"
+    connect_help = [
+        "Open developer.twitter.com/en/portal/dashboard",
+        "Sign up for a developer account if you haven't (free tier works for posting)",
+        "Create a Project, then a Standalone App inside it",
+        "App settings → User authentication settings → enable OAuth 1.0a with Read+Write",
+        "Keys and tokens tab → copy Consumer Key + Consumer Secret",
+        "Scroll down → Generate Access Token + Secret → copy both",
+    ]
+    fields = [
+        {"key": "api_key", "label": "Consumer Key", "placeholder": "Enter Consumer key", "password": True},
+        {"key": "api_secret", "label": "Consumer Secret", "placeholder": "Enter Consumer secret", "password": True},
+        {"key": "access_token", "label": "Access Token", "placeholder": "Enter access token", "password": True},
+        {"key": "access_token_secret", "label": "Access Token Secret", "placeholder": "Enter access token secret", "password": True},
+    ]
+    config_class = TwitterConfig
+    config_fields = [
+        {"key": "watch_tag", "label": "Watch tag", "type": "text",
+         "placeholder": "@craftbot",
+         "help": "Trigger keyword in mentions. Leave empty to react to all mentions."},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 4:
+            return False, (
+                "Usage: /twitter login <api_key> <api_secret> <access_token> <access_token_secret>\n"
+                "Get these from developer.x.com"
+            )
+        api_key, api_secret, access_token, access_token_secret = (
+            args[0].strip(), args[1].strip(), args[2].strip(), args[3].strip()
+        )
+
+        url = "https://api.twitter.com/2/users/me"
+        params = {"user.fields": "id,name,username"}
+        auth_hdr = _oauth1_header("GET", url, params, api_key, api_secret, access_token, access_token_secret)
+        result = http_request("GET", url, headers={"Authorization": auth_hdr},
+                              params=params, expected=(200,))
+        if "error" in result:
+            return False, (
+                f"Twitter auth failed: {result['error']}. "
+                f"Check your API credentials.\nGet them from developer.x.com → Dashboard → Keys and tokens"
+            )
+        data = (result["result"] or {}).get("data", {})
+
+        save_credential(self.spec.cred_file, TwitterCredential(
+            api_key=api_key,
+            api_secret=api_secret,
+            access_token=access_token,
+            access_token_secret=access_token_secret,
+            user_id=data.get("id", ""),
+            username=data.get("username", ""),
+        ))
+        return True, f"Twitter/X connected as @{data.get('username')} ({data.get('name', '')})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No Twitter credentials found."
+        try:
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        remove_credential(self.spec.cred_file)
+        return True, "Removed Twitter credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "Twitter/X: Not connected"
+        cred = load_credential(self.spec.cred_file, TwitterCredential)
+        if not cred:
+            return True, "Twitter/X: Not connected"
+        username = cred.username or "unknown"
+        cfg = load_config(_twitter_config_file(), TwitterConfig) or TwitterConfig()
+        tag_info = f" [tag: {cfg.watch_tag}]" if cfg.watch_tag else ""
+        return True, f"Twitter/X: Connected\n  - @{username}{tag_info}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class TwitterClient(BasePlatformClient):
+    spec = TWITTER
+    PLATFORM_ID = TWITTER.platform_id
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[TwitterCredential] = None
+        self._poll_task: Optional[asyncio.Task] = None
+        self._since_id: Optional[str] = None
+        self._seen_ids: set = set()
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> TwitterCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, TwitterCredential)
+        if self._cred is None:
+            raise RuntimeError("No Twitter credentials. Use /twitter login first.")
+        return self._cred
+
+    def _auth_header(self, method: str, url: str, params: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        cred = self._load()
+        return {
+            "Authorization": _oauth1_header(
+                method, url, params or {},
+                cred.api_key, cred.api_secret,
+                cred.access_token, cred.access_token_secret,
+            ),
+        }
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return await self.post_tweet(text, reply_to=recipient if recipient else None)
+
+    def _config(self) -> TwitterConfig:
+        return load_config(_twitter_config_file(), TwitterConfig) or TwitterConfig()
+
+    def get_watch_tag(self) -> str:
+        return self._config().watch_tag
+
+    def set_watch_tag(self, tag: str) -> None:
+        cfg = self._config()
+        cfg.watch_tag = tag.strip()
+        save_config(_twitter_config_file(), cfg)
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            return
+        self._message_callback = callback
+        cred = self._load()
+
+        me = await self.get_me()
+        if "error" in me:
+            raise RuntimeError(f"Invalid Twitter credentials: {me.get('error')}")
+
+        user_data = me.get("result", {})
+        username = user_data.get("username", "unknown")
+        user_id = user_data.get("id", "")
+
+        if cred.username != username or cred.user_id != user_id:
+            cred.username = username
+            cred.user_id = user_id
+            save_credential(self.spec.cred_file, cred)
+            self._cred = cred
+
+        self._listening = True
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+        self._poll_task = None
+
+    async def _poll_loop(self) -> None:
+        try:
+            await self._catchup()
+        except Exception as e:
+            logger.warning(f"[TWITTER] Catchup error: {e}")
+
+        while self._listening:
+            try:
+                await self._check_mentions()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"[TWITTER] Poll error: {e}")
+                await asyncio.sleep(RETRY_DELAY)
+                continue
+            await asyncio.sleep(POLL_INTERVAL)
+
+    async def _catchup(self) -> None:
+        cred = self._load()
+        if not cred.user_id:
+            return
+        url = f"{TWITTER_API}/users/{cred.user_id}/mentions"
+        params = {"max_results": "5", "tweet.fields": "created_at,author_id,text"}
+        result = await arequest("GET", url, headers=self._auth_header("GET", url, params),
+                                params=params, expected=(200,))
+        if "error" in result:
+            return
+        tweets = (result["result"] or {}).get("data", [])
+        if tweets:
+            self._since_id = tweets[0].get("id")
+            for t in tweets:
+                self._seen_ids.add(t.get("id"))
+
+    async def _check_mentions(self) -> None:
+        cred = self._load()
+        if not cred.user_id:
+            return
+        url = f"{TWITTER_API}/users/{cred.user_id}/mentions"
+        params: Dict[str, str] = {
+            "max_results": "20",
+            "tweet.fields": "created_at,author_id,text,in_reply_to_user_id,conversation_id",
+            "expansions": "author_id",
+            "user.fields": "username,name",
+        }
+        if self._since_id:
+            params["since_id"] = self._since_id
+
+        result = await arequest("GET", url, headers=self._auth_header("GET", url, params),
+                                params=params, expected=(200,))
+        if "error" in result:
+            if "429" in result["error"]:
+                await asyncio.sleep(60)
+            else:
+                logger.warning(f"[TWITTER] Mentions API {result['error']}")
+            return
+
+        data = result["result"] or {}
+        tweets = data.get("data", [])
+        if not tweets:
+            return
+
+        users_map = {u["id"]: u for u in data.get("includes", {}).get("users", [])}
+        self._since_id = tweets[0].get("id")
+
+        for tweet in reversed(tweets):
+            tid = tweet.get("id", "")
+            if tid in self._seen_ids:
+                continue
+            self._seen_ids.add(tid)
+            await self._dispatch_mention(tweet, users_map)
+
+        if len(self._seen_ids) > 500:
+            self._seen_ids = set(list(self._seen_ids)[-200:])
+
+    async def _dispatch_mention(self, tweet: Dict[str, Any], users_map: Dict[str, Any]) -> None:
+        if not self._message_callback:
+            return
+
+        text = tweet.get("text", "")
+        author_id = tweet.get("author_id", "")
+        author_info = users_map.get(author_id, {})
+        author_username = author_info.get("username", "")
+        author_name = author_info.get("name", author_username)
+
+        watch_tag = self._config().watch_tag
+        if watch_tag:
+            if watch_tag.lower() not in text.lower():
+                return
+            tag_lower = watch_tag.lower()
+            idx = text.lower().find(tag_lower)
+            instruction = text[idx + len(watch_tag):].strip() if idx >= 0 else text
+        else:
+            instruction = text
+
+        clean_instruction = instruction
+        while clean_instruction.startswith("@"):
+            parts = clean_instruction.split(" ", 1)
+            clean_instruction = parts[1].strip() if len(parts) > 1 else ""
+
+        timestamp = None
+        try:
+            timestamp = datetime.fromisoformat(tweet.get("created_at", "").replace("Z", "+00:00"))
+        except Exception:
+            pass
+
+        await self._message_callback(PlatformMessage(
+            platform=self.spec.platform_id,
+            sender_id=author_id,
+            sender_name=f"@{author_username}" if author_username else author_name,
+            text=f"@{author_username}: {clean_instruction or text}",
+            channel_id=tweet.get("conversation_id", ""),
+            channel_name="Twitter/X",
+            message_id=tweet.get("id", ""),
+            timestamp=timestamp,
+            raw={
+                "tweet": tweet,
+                "trigger": "mention" if not watch_tag else "mention_tag",
+                "tag": watch_tag,
+                "instruction": clean_instruction or text,
+                "author_username": author_username,
+            },
+        ))
+
+    # ----- API methods -----
+
+    async def get_me(self) -> Result:
+        url = f"{TWITTER_API}/users/me"
+        params = {"user.fields": "id,name,username,description,public_metrics"}
+        return await arequest(
+            "GET", url, headers=self._auth_header("GET", url, params),
+            params=params, expected=(200,),
+            transform=lambda d: d.get("data", {}),
+        )
+
+    async def post_tweet(self, text: str, reply_to: Optional[str] = None) -> Result:
+        url = f"{TWITTER_API}/tweets"
+        payload: Dict[str, Any] = {"text": text}
+        if reply_to:
+            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
+        return await arequest(
+            "POST", url,
+            headers={**self._auth_header("POST", url), "Content-Type": "application/json"},
+            json=payload,
+            transform=lambda d: {"id": d.get("data", {}).get("id"),
+                                  "text": d.get("data", {}).get("text")},
+        )
+
+    async def delete_tweet(self, tweet_id: str) -> Result:
+        url = f"{TWITTER_API}/tweets/{tweet_id}"
+        return await arequest(
+            "DELETE", url, headers=self._auth_header("DELETE", url),
+            expected=(200,),
+            transform=lambda _d: {"deleted": True},
+        )
+
+    async def get_user_timeline(self, user_id: Optional[str] = None, max_results: int = 10) -> Result:
+        cred = self._load()
+        uid = user_id or cred.user_id
+        if not uid:
+            return {"error": "No user_id available"}
+        url = f"{TWITTER_API}/users/{uid}/tweets"
+        params = {"max_results": str(max_results), "tweet.fields": "created_at,public_metrics,text"}
+        return await arequest(
+            "GET", url, headers=self._auth_header("GET", url, params),
+            params=params, expected=(200,),
+        )
+
+    async def search_tweets(self, query: str, max_results: int = 10) -> Result:
+        url = f"{TWITTER_API}/tweets/search/recent"
+        params = {"query": query, "max_results": str(max_results),
+                  "tweet.fields": "created_at,author_id,public_metrics,text",
+                  "expansions": "author_id", "user.fields": "username"}
+        return await arequest(
+            "GET", url, headers=self._auth_header("GET", url, params),
+            params=params, expected=(200,),
+        )
+
+    async def like_tweet(self, tweet_id: str) -> Result:
+        cred = self._load()
+        url = f"{TWITTER_API}/users/{cred.user_id}/likes"
+        return await arequest(
+            "POST", url,
+            headers={**self._auth_header("POST", url), "Content-Type": "application/json"},
+            json={"tweet_id": tweet_id}, expected=(200,),
+            transform=lambda d: d.get("data", {}),
+        )
+
+    async def retweet(self, tweet_id: str) -> Result:
+        cred = self._load()
+        url = f"{TWITTER_API}/users/{cred.user_id}/retweets"
+        return await arequest(
+            "POST", url,
+            headers={**self._auth_header("POST", url), "Content-Type": "application/json"},
+            json={"tweet_id": tweet_id}, expected=(200,),
+            transform=lambda d: d.get("data", {}),
+        )
+
+    async def get_user_by_username(self, username: str) -> Result:
+        url = f"{TWITTER_API}/users/by/username/{username}"
+        params = {"user.fields": "id,name,username,description,public_metrics"}
+        return await arequest(
+            "GET", url, headers=self._auth_header("GET", url, params),
+            params=params, expected=(200,),
+            transform=lambda d: d.get("data", {}),
+        )
+
+    async def reply_to_tweet(self, tweet_id: str, text: str) -> Result:
+        return await self.post_tweet(text, reply_to=tweet_id)
diff --git a/craftos_integrations/integrations/whatsapp_business/INTEGRATION.md b/craftos_integrations/integrations/whatsapp_business/INTEGRATION.md
new file mode 100644
index 00000000..019fe670
--- /dev/null
+++ b/craftos_integrations/integrations/whatsapp_business/INTEGRATION.md
@@ -0,0 +1,12 @@
+# WhatsApp Business — Integration Reference
+
+WhatsApp Business Cloud API (Meta Graph). Enterprise integration with access token + `phone_number_id` — completely different from the QR-based `whatsapp_web`.
+
+## Essentials
+
+- **Not `whatsapp_web`.** No QR scan, no browser bridge. Outbound only via the Cloud API; incoming requires Meta webhook setup (not auto-listened by this integration). Don't confuse the two.
+- **`phone_number_id` is a Meta numeric ID, NOT a phone number.** The router should never ask the user for "your WhatsApp number" — `cred.phone_number_id` is the From identity, resolved from the Meta dashboard at connect time.
+- **Recipients are bare E.164 phone numbers** (e.g. `"14155552671"`). No `@c.us` / `@lid` JID format like `whatsapp_web`. Pass the digits only — no `+`, no formatting.
+- **24-hour customer-service window.** Free-form text via `send_whatsapp_business_text` only works if the recipient sent you a message in the last 24h. Outside that window you MUST use `send_whatsapp_business_template` with a pre-approved template (created in Meta dashboard).
+- **Templates need `template_name`, `language_code`, and components** (placeholder fills). The template itself must already exist in the user's Meta Business account — the router can't create templates on the fly.
+- **No contact search, no chat history.** Unlike `whatsapp_web`, there are no `search_contact` / `get_chat_messages` actions. The recipient phone must come from the user or from an incoming webhook payload — not from a stored contact list.
diff --git a/craftos_integrations/integrations/whatsapp_business/__init__.py b/craftos_integrations/integrations/whatsapp_business/__init__.py
new file mode 100644
index 00000000..a6f23cbc
--- /dev/null
+++ b/craftos_integrations/integrations/whatsapp_business/__init__.py
@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""WhatsApp Business Cloud API integration."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    has_credential,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...helpers import Result, request as http_request
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+GRAPH_API_BASE = "https://graph.facebook.com/v21.0"
+
+
+@dataclass
+class WhatsAppBusinessCredential:
+    access_token: str = ""
+    phone_number_id: str = ""
+    app_secret: str = ""
+    verify_token: str = ""
+
+
+WAB = IntegrationSpec(
+    name="whatsapp_business",
+    cred_class=WhatsAppBusinessCredential,
+    cred_file="whatsapp_business.json",
+    platform_id="whatsapp_business",
+)
+
+
+# -----------------------------------------------------------------
+# Handler
+# -----------------------------------------------------------------
+
+@register_handler(WAB.name)
+class WhatsAppBusinessHandler(IntegrationHandler):
+    spec = WAB
+    display_name = "WhatsApp Business"
+    description = "WhatsApp Cloud API"
+    auth_type = "token"
+    icon = "whatsapp_business"
+    connect_help = [
+        "Open developers.facebook.com/apps and create an app (Business type)",
+        "Add the 'WhatsApp' product to the app",
+        "WhatsApp → API Setup tab - copy the temporary access token (or generate a permanent one in System Users)",
+        "Same page - copy the Phone Number ID under 'From' phone number",
+        "Add a recipient phone number for testing on the same page",
+    ]
+    fields = [
+        {"key": "access_token", "label": "Access Token", "placeholder": "Enter access token", "password": True},
+        {"key": "phone_number_id", "label": "Phone Number ID", "placeholder": "Enter phone number ID", "password": False},
+    ]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        if len(args) < 2:
+            return False, "Usage: /whatsapp-business login <access_token> <phone_number_id>"
+        access_token, phone_number_id = args[0], args[1]
+
+        result = http_request(
+            "GET", f"{GRAPH_API_BASE}/{phone_number_id}",
+            headers={"Authorization": f"Bearer {access_token}"},
+            expected=(200,),
+        )
+        if "error" in result:
+            return False, f"Invalid credentials: {result['error']}"
+
+        save_credential(self.spec.cred_file, WhatsAppBusinessCredential(
+            access_token=access_token, phone_number_id=phone_number_id,
+        ))
+        return True, f"WhatsApp Business connected (phone number ID: {phone_number_id})"
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No WhatsApp Business credentials found."
+        remove_credential(self.spec.cred_file)
+        return True, "Removed WhatsApp Business credential."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "WhatsApp Business: Not connected"
+        cred = load_credential(self.spec.cred_file, WhatsAppBusinessCredential)
+        pid = cred.phone_number_id if cred else "unknown"
+        return True, f"WhatsApp Business: Connected\n  - Phone Number ID: {pid}"
+
+
+# -----------------------------------------------------------------
+# Client
+# -----------------------------------------------------------------
+
+@register_client
+class WhatsAppBusinessClient(BasePlatformClient):
+    spec = WAB
+    PLATFORM_ID = WAB.platform_id
+
+    def __init__(self):
+        super().__init__()
+        self._cred: Optional[WhatsAppBusinessCredential] = None
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> WhatsAppBusinessCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, WhatsAppBusinessCredential)
+        if self._cred is None:
+            raise RuntimeError("No WhatsApp Business credentials. Use /whatsapp-business login first.")
+        return self._cred
+
+    def _headers(self) -> Dict[str, str]:
+        cred = self._load()
+        return {"Authorization": f"Bearer {cred.access_token}", "Content-Type": "application/json"}
+
+    async def connect(self) -> None:
+        self._load()
+        self._connected = True
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Result:
+        return self.send_text(recipient, text)
+
+    def _messages_url(self) -> str:
+        return f"{GRAPH_API_BASE}/{self._load().phone_number_id}/messages"
+
+    def send_text(self, to: str, text: str) -> Result:
+        return http_request(
+            "POST", self._messages_url(), headers=self._headers(),
+            json={"messaging_product": "whatsapp", "to": to, "type": "text", "text": {"body": text}},
+        )
+
+    def send_template(self, to: str, template_name: str, language_code: str = "en_US",
+                      components: Optional[List[Dict[str, Any]]] = None) -> Result:
+        template: Dict[str, Any] = {"name": template_name, "language": {"code": language_code}}
+        if components:
+            template["components"] = components
+        return http_request(
+            "POST", self._messages_url(), headers=self._headers(),
+            json={"messaging_product": "whatsapp", "to": to, "type": "template", "template": template},
+        )
+
+    def send_image(self, to: str, image_url: str, caption: Optional[str] = None) -> Result:
+        image: Dict[str, Any] = {"link": image_url}
+        if caption:
+            image["caption"] = caption
+        return http_request(
+            "POST", self._messages_url(), headers=self._headers(),
+            json={"messaging_product": "whatsapp", "to": to, "type": "image", "image": image},
+        )
+
+    def send_document(self, to: str, document_url: str, filename: Optional[str] = None,
+                      caption: Optional[str] = None) -> Result:
+        doc: Dict[str, Any] = {"link": document_url}
+        if filename:
+            doc["filename"] = filename
+        if caption:
+            doc["caption"] = caption
+        return http_request(
+            "POST", self._messages_url(), headers=self._headers(),
+            json={"messaging_product": "whatsapp", "to": to, "type": "document", "document": doc},
+        )
+
+    def mark_as_read(self, message_id: str) -> Result:
+        return http_request(
+            "POST", self._messages_url(), headers=self._headers(),
+            json={"messaging_product": "whatsapp", "status": "read", "message_id": message_id},
+            expected=(200,),
+        )
+
+    def get_media_url(self, media_id: str) -> Result:
+        return http_request(
+            "GET", f"{GRAPH_API_BASE}/{media_id}", headers=self._headers(),
+            expected=(200,),
+            transform=lambda d: {"url": d.get("url"), "mime_type": d.get("mime_type"), "file_size": d.get("file_size")},
+        )
+
+    def get_business_profile(self) -> Result:
+        cred = self._load()
+        return http_request(
+            "GET", f"{GRAPH_API_BASE}/{cred.phone_number_id}/whatsapp_business_profile",
+            headers=self._headers(),
+            params={"fields": "about,address,description,email,profile_picture_url,websites,vertical"},
+            expected=(200,),
+            transform=lambda d: d.get("data", [{}])[0] if d.get("data") else d,
+        )
diff --git a/craftos_integrations/integrations/whatsapp_web/INTEGRATION.md b/craftos_integrations/integrations/whatsapp_web/INTEGRATION.md
new file mode 100644
index 00000000..ac6108e2
--- /dev/null
+++ b/craftos_integrations/integrations/whatsapp_web/INTEGRATION.md
@@ -0,0 +1,81 @@
+# WhatsApp Web — Integration Reference
+
+Operational notes the action schemas can't fit. Grep here before asking the user.
+
+## Essentials
+
+Routing-time guidance — these are the rules that the agent loses sight of most often. Read these *before* deciding what to do.
+
+- **The bridge knows the logged-in user's own phone, name, and JID.** Never ask the user for them — call `get_whatsapp_web_session_status` to look them up. Required for any "send to my WhatsApp" / "message myself" request.
+- **Self-send shortcut:** `to: "user"` (also `"me"`, `"self"`, `"owner"`) is auto-resolved to the owner's phone by the integration. No lookup needed.
+- **Sending by name (not number):** call `search_whatsapp_contact` first, then pass the result's `number` field **verbatim** as `to` in `send_whatsapp_web_text_message`. Do NOT strip `@lid` or `@c.us` suffixes — they're part of valid JIDs.
+- **Identity formats:** both `<phone>@c.us` and `<id>@lid` are valid JIDs. The bare `<id>` part of a `@lid` JID is **not** a phone number and must not be dialled or sent to `getNumberId`.
+- **Common errors:** `Number X is not on WhatsApp` after a search → you stripped a JID suffix; pass it back exactly as the search returned it. `Client not ready` → bridge is starting or waiting for a QR scan; surface to the user, don't retry blindly.
+
+## Architecture
+
+A Node subprocess (`bridge.js`) wraps `whatsapp-web.js` and talks to the Python side over stdin/stdout JSON lines. Commands like `send_message`, `search_contact`, `get_chat_messages` map 1:1 to bridge cases. Errors surface back as `{success: false, error: "..."}`.
+
+## Session-level facts the bridge already knows
+
+Once `Client ready` fires, the bridge knows everything about the logged-in account. **Never ask the user for any of this** — call `get_whatsapp_web_session_status` instead:
+
+- `owner_phone` — the user's own phone number (E.164 without `+`), e.g. `"447417378160"`.
+- `owner_name` — the user's WhatsApp display name (pushname).
+- `wid` — the user's full JID (`<phone>@c.us` or `<id>@lid`).
+- `ready` — whether the session is actually live; `false` means QR scan pending or bridge starting up.
+
+Send-to-self works with either `to: "user"` (magic value) or `to: <owner_phone>`.
+
+## Identity formats — `@c.us` vs `@lid`
+
+WhatsApp uses two JID shapes:
+
+- `<phone>@c.us` — phone-based. The `<phone>` part is a dialable number (E.164 without `+`).
+- `<lid_user>@lid` — LID (Linked ID) based. The `<lid_user>` part is an **opaque numeric ID**, NOT a phone number. You cannot dial it, and you cannot resolve it via `getNumberId`. It's only meaningful as a full JID.
+
+Modern WhatsApp creates `@lid` identities for many contacts. `search_whatsapp_contact` will return them when applicable.
+
+## Canonical workflows
+
+### Send a message by name (no number known)
+
+1. Call `search_whatsapp_contact` with `name`.
+2. Pick the best match from `contacts[]`.
+3. Pass the match's `number` field **verbatim** as `to` in `send_whatsapp_web_text_message`.
+   - Do NOT strip `@lid` or `@c.us` suffixes.
+   - Do NOT keep only the digits.
+   - The bridge routes anything containing `@` straight through to the wwebjs send path.
+
+### Send a message by phone number
+
+Pass the phone number directly (e.g. `"447417378160"`). The bridge runs `getNumberId` server-side to resolve and verify. Returns `Number X is not on WhatsApp` if the number isn't registered.
+
+### Search
+
+`search_whatsapp_contact` searches **chats first** (fast, covers anyone you've messaged) and falls back to an in-page filter against `window.Store.Contact` if zero chat matches. Either way, the result shape is `{id, name, number, is_group}`.
+
+For LID-based results, both `id` and `number` are the full `xxx@lid` JID — the bridge never returns a bare LID user portion, because that's not a usable identifier anywhere.
+
+## Known errors
+
+| Error | What it means | Fix |
+|---|---|---|
+| `Number X is not on WhatsApp` | Either a wrong number, OR you stripped a JID suffix you shouldn't have. | Re-check that `to` is the exact `number` value from `search_whatsapp_contact`. |
+| `No LID for user` | wwebjs couldn't resolve a phone → LID for a cold contact. | Use the JID from `search_whatsapp_contact` instead of constructing one locally. |
+| `Client not ready` | Bridge is starting up or waiting for a QR scan. | Wait for the `ready` event, or have the user scan the QR. |
+| `Command 'search_contact' timed out` | Historical — the old code called `getContacts()` which round-tripped every contact across RPC. Fixed by chat-first search. | Should not happen on current code. If it does, the bridge is stuck. |
+
+## Group chats
+
+- Group JIDs end in `@g.us` (e.g. `<group_id>@g.us`). They appear in `search_whatsapp_contact` results with `is_group: true`.
+- Sending to a group is the same call as sending to a person: pass the group JID as `to` in `send_whatsapp_web_text_message`.
+- `get_whatsapp_chat_history` works on group JIDs too — same `phone_number` arg accepts either a phone or a JID.
+
+## Quirks
+
+- The bridge restarts with the agent. There's a startup window (typically <10s after the agent boots) before `Client ready` fires. Calls before then return `Client not ready`.
+- `Catchup complete: N unread chat(s)` fires shortly after `ready`. The unread list is emitted as a `catchup` event, not a return value — wait for it if you need fresh unread state on boot.
+- `to: "user"` is a magic value some send actions accept that means "send to yourself" (the WhatsApp account's own number). It's not a contact lookup.
+- There is **no built-in rate limit** on the bridge. WhatsApp itself will block accounts that send to many unknown contacts in a short window — don't bulk-send to cold contacts.
+- If the user is disconnected (`ready: false`), retrying a send won't help — the user needs to re-scan a QR. Surface that clearly rather than retrying in a loop.
diff --git a/craftos_integrations/integrations/whatsapp_web/__init__.py b/craftos_integrations/integrations/whatsapp_web/__init__.py
new file mode 100644
index 00000000..6720c034
--- /dev/null
+++ b/craftos_integrations/integrations/whatsapp_web/__init__.py
@@ -0,0 +1,675 @@
+# -*- coding: utf-8 -*-
+"""WhatsApp Web integration — handler + client + QR-session helpers.
+
+The QR session helpers (``start_qr_session`` / ``check_qr_session_status``
+/ ``cancel_qr_session``) provide a stateful login flow for non-blocking
+UIs (web settings page, etc.) that need to poll instead of awaiting the
+QR scan synchronously.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+import tempfile
+import webbrowser
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+from ... import (
+    BasePlatformClient,
+    IntegrationHandler,
+    IntegrationSpec,
+    PlatformMessage,
+    has_credential,
+    load_config,
+    load_credential,
+    register_client,
+    register_handler,
+    remove_credential,
+    save_credential,
+)
+from ...config import ConfigStore
+from ...logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class WhatsAppWebCredential:
+    session_id: str = ""
+    owner_phone: str = ""
+    owner_name: str = ""
+
+
+@dataclass
+class WhatsAppWebConfig:
+    """Runtime knobs persisted to ``whatsapp_web_config.json``."""
+    # When True, only forward messages the owner sent to themselves
+    # (self-chat). All other incoming messages — DMs from contacts, group
+    # chats — are dropped before reaching the agent. Useful when the user
+    # wants WhatsApp to act as a personal command channel only.
+    self_messages_only: bool = False
+
+
+WHATSAPP_WEB = IntegrationSpec(
+    name="whatsapp_web",
+    cred_class=WhatsAppWebCredential,
+    cred_file="whatsapp_web.json",
+    platform_id="whatsapp_web",
+)
+
+
+def _whatsapp_web_config_file() -> str:
+    """``whatsapp_web.json`` → ``whatsapp_web_config.json``."""
+    stem = WHATSAPP_WEB.cred_file
+    return (stem[:-5] if stem.endswith(".json") else stem) + "_config.json"
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Handler
+# ════════════════════════════════════════════════════════════════════════
+
+@register_handler(WHATSAPP_WEB.name)
+class WhatsAppWebHandler(IntegrationHandler):
+    spec = WHATSAPP_WEB
+    display_name = "WhatsApp"
+    description = "Messaging via Web (QR code)"
+    auth_type = "interactive"
+    config_class = WhatsAppWebConfig
+    config_fields = [
+        {"key": "self_messages_only", "label": "Self-messages only", "type": "checkbox",
+         "help": "Only forward messages you send to yourself (the WhatsApp self-chat). "
+                 "Drops incoming DMs and group messages before they reach the agent."},
+    ]
+    icon = "whatsapp"
+    fields: List = []
+
+    @property
+    def subcommands(self) -> List[str]:
+        return ["login", "logout", "status"]
+
+    async def login(self, args: List[str]) -> Tuple[bool, str]:
+        try:
+            from ._bridge_client import get_whatsapp_bridge
+        except ImportError:
+            return False, "WhatsApp bridge not available. Ensure Node.js >= 18 is installed."
+
+        bridge = get_whatsapp_bridge()
+        if not bridge.is_running:
+            try:
+                await bridge.start()
+            except Exception as e:
+                return False, f"Failed to start WhatsApp bridge: {e}"
+
+        event_type, event_data = await bridge.wait_for_qr_or_ready(timeout=60.0)
+
+        if event_type == "ready":
+            owner_phone = bridge.owner_phone or ""
+            owner_name = bridge.owner_name or ""
+            save_credential(self.spec.cred_file, WhatsAppWebCredential(
+                session_id="bridge", owner_phone=owner_phone, owner_name=owner_name,
+            ))
+            display = owner_phone or owner_name or "connected"
+            return True, f"WhatsApp Web connected: +{display}"
+
+        if event_type == "qr":
+            qr_string = (event_data or {}).get("qr_string", "")
+            if qr_string:
+                try:
+                    import qrcode
+                    qr = qrcode.QRCode(border=1)
+                    qr.add_data(qr_string)
+                    qr.make(fit=True)
+                    matrix = qr.get_matrix()
+                    lines = ["".join("##" if cell else "  " for cell in row) for row in matrix]
+                    sys.stderr.write("\n" + "\n".join(lines) + "\n\n")
+                    sys.stderr.write("Scan the QR code above with WhatsApp on your phone\n\n")
+                    sys.stderr.flush()
+                except Exception:
+                    pass
+
+            qr_data_url = (event_data or {}).get("qr_data_url")
+            if qr_data_url:
+                import base64 as b64
+                qr_b64 = qr_data_url
+                if qr_b64.startswith("data:image"):
+                    qr_b64 = qr_b64.split(",", 1)[1]
+                qr_path = os.path.join(tempfile.gettempdir(), "whatsapp_qr_bridge.png")
+                with open(qr_path, "wb") as f:
+                    f.write(b64.b64decode(qr_b64))
+                webbrowser.open(f"file://{qr_path}")
+
+            ready = await bridge.wait_for_ready(timeout=120.0)
+            if not ready:
+                return False, "Timed out waiting for QR scan. Run /whatsapp_web login again."
+
+            owner_phone = bridge.owner_phone or ""
+            owner_name = bridge.owner_name or ""
+            save_credential(self.spec.cred_file, WhatsAppWebCredential(
+                session_id="bridge", owner_phone=owner_phone, owner_name=owner_name,
+            ))
+            display = owner_phone or owner_name or "connected"
+            return True, f"WhatsApp Web connected: +{display}"
+
+        return False, "Timed out waiting for WhatsApp bridge. Run /whatsapp_web login again."
+
+    async def logout(self, args: List[str]) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return False, "No WhatsApp credentials found."
+        remove_credential(self.spec.cred_file)
+        try:
+            from ._bridge_client import get_whatsapp_bridge
+            bridge = get_whatsapp_bridge()
+            # ``logout()`` (not ``stop()``) — calls wwebjs's ``client.logout()``
+            # which invalidates the session server-side and wipes the LocalAuth
+            # data on disk. Without this, the next connect would silently
+            # auto-restore the session and skip the QR scan, which makes the
+            # disconnect ineffectual from the user's point of view.
+            if bridge.is_running:
+                await bridge.logout()
+            else:
+                # Bridge isn't running but LocalAuth data may still exist
+                # from a previous session — wipe it directly.
+                import shutil
+                from pathlib import Path
+                from ...config import ConfigStore
+                shutil.rmtree(
+                    Path(ConfigStore.project_root) / ".credentials" / "whatsapp_wwebjs_auth",
+                    ignore_errors=True,
+                )
+            from ...manager import get_external_comms_manager
+            manager = get_external_comms_manager()
+            if manager:
+                await manager.stop_platform(self.spec.platform_id)
+        except Exception:
+            pass
+        return True, "WhatsApp disconnected."
+
+    async def status(self) -> Tuple[bool, str]:
+        if not has_credential(self.spec.cred_file):
+            return True, "WhatsApp: Not connected"
+        cred = load_credential(self.spec.cred_file, WhatsAppWebCredential)
+        if not cred:
+            return True, "WhatsApp: Not connected"
+        phone = cred.owner_phone or "unknown"
+        name = cred.owner_name or ""
+        label = f"+{phone}" + (f" ({name})" if name else "")
+        return True, f"WhatsApp: Connected\n  - {label}"
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Client
+# ════════════════════════════════════════════════════════════════════════
+
+@register_client
+class WhatsAppWebClient(BasePlatformClient):
+    spec = WHATSAPP_WEB
+    PLATFORM_ID = WHATSAPP_WEB.platform_id
+
+    _OWNER_ALIASES = {"user", "owner", "me", "self"}
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._cred: Optional[WhatsAppWebCredential] = None
+        self._bridge = None
+        self._seen_ids: set = set()
+        self._known_groups: set = set()
+        self._agent_sent_ids: set = set()
+
+    @property
+    def _agent_prefix(self) -> str:
+        name = ConfigStore.extras.get("agent_name", "AGENT")
+        return f"[{name}] "
+
+    def has_credentials(self) -> bool:
+        return has_credential(self.spec.cred_file)
+
+    def _load(self) -> WhatsAppWebCredential:
+        if self._cred is None:
+            self._cred = load_credential(self.spec.cred_file, WhatsAppWebCredential)
+        if self._cred is None:
+            raise RuntimeError("No WhatsApp Web credentials found. Please log in first.")
+        return self._cred
+
+    @property
+    def owner_phone(self) -> str:
+        return self._load().owner_phone
+
+    def _get_bridge(self):
+        if self._bridge is None:
+            from ._bridge_client import get_whatsapp_bridge
+            self._bridge = get_whatsapp_bridge()
+        return self._bridge
+
+    async def connect(self) -> None:
+        bridge = self._get_bridge()
+        if not bridge.is_running:
+            await bridge.start()
+        if not bridge.is_ready:
+            ready = await bridge.wait_for_ready(timeout=120.0)
+            if not ready:
+                raise RuntimeError("WhatsApp bridge did not become ready within timeout")
+        self._connected = True
+
+    async def disconnect(self) -> None:
+        await super().disconnect()
+        bridge = self._get_bridge()
+        if bridge.is_running:
+            await bridge.stop()
+
+    def _resolve_recipient(self, recipient: str) -> str:
+        if recipient.strip().lower() in self._OWNER_ALIASES:
+            phone = self.owner_phone
+            if phone:
+                return phone
+        return recipient
+
+    async def send_message(self, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+        bridge = self._get_bridge()
+        if not bridge.is_ready:
+            return {"status": "error", "error": "Bridge not ready"}
+        resolved = self._resolve_recipient(recipient)
+        prefixed_text = f"{self._agent_prefix}{text}"
+        result = await bridge.send_message(to=resolved, text=prefixed_text)
+        msg_id = result.get("message_id")
+        if msg_id:
+            self._agent_sent_ids.add(msg_id)
+        return {"status": "success" if result.get("success") else "error", **result}
+
+    async def send_media(self, recipient: str, media_path: str,
+                         caption: Optional[str] = None) -> Dict[str, Any]:
+        if caption:
+            return await self.send_message(recipient, f"[Media: {media_path}]\n{caption}")
+        return {"status": "error", "error": "Media sending not yet supported via bridge"}
+
+    async def get_chat_messages(self, phone_number: str, limit: int = 50) -> Dict[str, Any]:
+        bridge = self._get_bridge()
+        if not bridge.is_ready:
+            return {"success": False, "error": "Bridge not ready"}
+        result = await bridge.get_chat_messages(chat_id=phone_number, limit=limit)
+        return {"status": "success" if result.get("success") else "error", **result}
+
+    async def get_unread_chats(self) -> Dict[str, Any]:
+        bridge = self._get_bridge()
+        if not bridge.is_ready:
+            return {"success": False, "error": "Bridge not ready"}
+        result = await bridge.get_unread_chats()
+        return {"status": "success" if result.get("success") else "error", **result}
+
+    async def search_contact(self, name: str) -> Dict[str, Any]:
+        bridge = self._get_bridge()
+        if not bridge.is_ready:
+            return {"success": False, "error": "Bridge not ready"}
+        result = await bridge.search_contact(name=name)
+        return {"status": "success" if result.get("success") else "error", **result}
+
+    async def get_session_status(self) -> Optional[Dict[str, Any]]:
+        bridge = self._get_bridge()
+        if not bridge.is_running:
+            return {"status": "disconnected", "ready": False}
+        try:
+            result = await bridge.get_status()
+            return {"status": "connected" if result.get("ready") else "waiting", **result}
+        except Exception:
+            return {"status": "disconnected", "ready": False}
+
+    @property
+    def supports_listening(self) -> bool:
+        return True
+
+    async def start_listening(self, callback) -> None:
+        if self._listening:
+            # Already wired to the bridge — just point at the new callback.
+            # Lets a new integration manager rewire onto a still-running
+            # bridge (e.g. between test_live tests) without tearing down
+            # and reattaching the wwebjs Playwright session. Production
+            # only calls start_listening once at boot, so this is a no-op
+            # there.
+            self._message_callback = callback
+            return
+        self._cred = None
+        bridge = self._get_bridge()
+
+        # Register the callback up-front so any event the bridge emits during
+        # startup (incl. a late "ready" after we return) flows through to us.
+        self._message_callback = callback
+        bridge.set_event_callback(self._on_bridge_event)
+
+        if bridge.is_running and bridge.is_ready:
+            event_type = "ready"
+        else:
+            if bridge.is_running:
+                await bridge.stop()
+                await asyncio.sleep(2)
+            await bridge.start()
+            # 180s gives whatsapp-web.js room to finish post-auth chat sync;
+            # on slower restarts the "ready" event can lag well behind the
+            # "authenticated" event.
+            event_type, _ = await bridge.wait_for_qr_or_ready(timeout=180.0)
+
+        if event_type == "qr":
+            # Need a fresh QR scan — credentials are stale, tear down.
+            bridge.set_event_callback(None)
+            await bridge.stop()
+            self._message_callback = None
+            return
+
+        # If wwebjs hasn't fired "ready" yet (timeout), don't fail —
+        # leave the bridge running with our callback wired. The "ready"
+        # event will arrive eventually (or won't, but the user will see
+        # status="waiting" rather than us tearing the session down).
+        if event_type != "ready":
+            logger.warning(
+                "[WHATSAPP_WEB] Bridge authenticated but 'ready' event not "
+                "received within 180s — leaving bridge running, listener will "
+                "activate when wwebjs finishes syncing."
+            )
+            self._listening = True
+            return
+
+        if bridge.owner_phone or bridge.owner_name:
+            cred = self._load()
+            if cred.owner_phone != bridge.owner_phone or cred.owner_name != bridge.owner_name:
+                updated = WhatsAppWebCredential(
+                    session_id=cred.session_id,
+                    owner_phone=bridge.owner_phone or cred.owner_phone,
+                    owner_name=bridge.owner_name or cred.owner_name,
+                )
+                save_credential(self.spec.cred_file, updated)
+                self._cred = updated
+
+        self._listening = True
+        self._connected = True
+
+    async def stop_listening(self) -> None:
+        if not self._listening:
+            return
+        self._listening = False
+        bridge = self._get_bridge()
+        bridge.set_event_callback(None)
+        # Send the bridge a clean ``shutdown`` command so wwebjs runs
+        # ``client.destroy()`` before the Node subprocess exits. Without this,
+        # the agent's Python process dies and Node gets killed by OS cleanup
+        # — WhatsApp's server treats that as a crash and invalidates the
+        # session faster than it would for a clean disconnect (which is what
+        # the desktop app sends on quit).
+        try:
+            await bridge.stop()
+        except Exception as e:
+            logger.warning(f"[WHATSAPP_WEB] Bridge stop error: {e}")
+
+    async def _on_bridge_event(self, event: str, data: Dict[str, Any]) -> None:
+        if event == "message":
+            await self._handle_incoming_message(data)
+        elif event == "message_sent":
+            await self._handle_sent_message(data)
+        elif event == "disconnected":
+            self._connected = False
+        elif event == "ready":
+            self._connected = True
+
+    async def _handle_incoming_message(self, data: Dict[str, Any]) -> None:
+        if not self._listening or not self._message_callback:
+            return
+
+        # Self-chat messages arrive via _handle_sent_message (from_me=True),
+        # so when self_messages_only is set we drop everything else here.
+        cfg = load_config(_whatsapp_web_config_file(), WhatsAppWebConfig) or WhatsAppWebConfig()
+        if cfg.self_messages_only:
+            return
+
+        msg_id = data.get("id", "")
+        if msg_id in self._seen_ids:
+            return
+        self._seen_ids.add(msg_id)
+
+        if data.get("from_me", False):
+            return
+
+        body = data.get("body", "")
+        if not body:
+            return
+
+        chat = data.get("chat", {})
+        contact = data.get("contact", {})
+        is_group = chat.get("is_group", False)
+        is_muted = chat.get("is_muted", False)
+        chat_name = chat.get("name", "")
+        if is_group:
+            self._known_groups.add(chat_name)
+        if is_muted and is_group:
+            return
+        if is_group and not self._is_mention_for_me(body):
+            return
+
+        sender_name = contact.get("name", "") or chat_name
+        sender_id = data.get("from", "")
+        timestamp = data.get("timestamp")
+
+        ts: Optional[datetime] = None
+        if timestamp:
+            try:
+                ts = datetime.fromtimestamp(timestamp, tz=timezone.utc)
+            except Exception:
+                ts = datetime.now(tz=timezone.utc)
+
+        await self._message_callback(PlatformMessage(
+            platform=self.PLATFORM_ID,
+            sender_id=sender_id,
+            sender_name=sender_name,
+            text=body,
+            channel_id=chat.get("id", ""),
+            channel_name=chat_name,
+            message_id=msg_id,
+            timestamp=ts,
+            raw={
+                "source": "WhatsApp Web", "integrationType": "whatsapp_web",
+                "is_self_message": False, "is_group": is_group,
+                "contactId": sender_id, "contactName": sender_name,
+                "messageBody": body, "chatId": chat.get("id", ""),
+                "chatName": chat_name, "timestamp": str(timestamp or ""),
+            },
+        ))
+
+    async def _handle_sent_message(self, data: Dict[str, Any]) -> None:
+        if not self._listening or not self._message_callback:
+            return
+        if not data.get("is_self_chat", False):
+            return
+
+        msg_id = data.get("id", "")
+        if msg_id in self._seen_ids:
+            return
+        self._seen_ids.add(msg_id)
+
+        if msg_id and msg_id in self._agent_sent_ids:
+            self._agent_sent_ids.discard(msg_id)
+            return
+
+        body = data.get("body", "")
+        if not body or body.startswith(self._agent_prefix):
+            return
+
+        chat = data.get("chat", {})
+        chat_name = chat.get("name", "")
+        timestamp = data.get("timestamp")
+
+        ts: Optional[datetime] = None
+        if timestamp:
+            try:
+                ts = datetime.fromtimestamp(timestamp, tz=timezone.utc)
+            except Exception:
+                ts = datetime.now(tz=timezone.utc)
+
+        await self._message_callback(PlatformMessage(
+            platform=self.PLATFORM_ID,
+            sender_id=data.get("from", ""),
+            sender_name=chat_name or "Self",
+            text=body,
+            channel_id=chat.get("id", ""),
+            channel_name=chat_name,
+            message_id=msg_id,
+            timestamp=ts,
+            raw={
+                "source": "WhatsApp Web", "integrationType": "whatsapp_web",
+                "is_self_message": True, "is_group": False,
+                "contactId": data.get("from", ""), "contactName": chat_name or "Self",
+                "messageBody": body, "chatId": chat.get("id", ""),
+                "chatName": chat_name, "timestamp": str(timestamp or ""),
+            },
+        ))
+
+    def _is_mention_for_me(self, text: str) -> bool:
+        if "@" not in text:
+            return False
+        text_lower = text.lower()
+        bridge = self._get_bridge()
+        own_name = bridge.owner_name if bridge else ""
+        if own_name:
+            own_lower = own_name.lower()
+            if f"@{own_lower}" in text_lower:
+                return True
+            first_name = own_lower.split()[0] if " " in own_lower else ""
+            if first_name and f"@{first_name}" in text_lower:
+                return True
+            return False
+        return True
+
+
+# ════════════════════════════════════════════════════════════════════════
+# QR-session helpers — for non-blocking UIs that poll
+# ════════════════════════════════════════════════════════════════════════
+
+_qr_sessions: Dict[str, Any] = {}
+
+
+async def start_qr_session() -> Dict[str, Any]:
+    """Start the bridge and return either ``qr_ready`` (with QR data URL) or
+    ``connected`` (already authenticated). Caller polls
+    ``check_qr_session_status(session_id)`` until ``connected``."""
+    try:
+        from ._bridge_client import get_whatsapp_bridge
+    except ImportError:
+        return {
+            "success": False, "status": "error",
+            "message": "WhatsApp bridge not available. Ensure Node.js >= 18 is installed.",
+        }
+
+    try:
+        bridge = get_whatsapp_bridge()
+        if not bridge.is_running:
+            await bridge.start()
+        event_type, event_data = await bridge.wait_for_qr_or_ready(timeout=60.0)
+
+        if event_type == "ready":
+            owner_phone = bridge.owner_phone or ""
+            owner_name = bridge.owner_name or ""
+            save_credential(WHATSAPP_WEB.cred_file, WhatsAppWebCredential(
+                session_id="bridge", owner_phone=owner_phone, owner_name=owner_name,
+            ))
+            display = owner_phone or owner_name or "connected"
+            return {
+                "success": True, "session_id": "bridge", "qr_code": "",
+                "status": "connected", "message": f"WhatsApp already connected: +{display}",
+            }
+
+        if event_type == "qr":
+            qr_data = (event_data or {}).get("qr_data_url", "")
+            if not qr_data:
+                qr_string = (event_data or {}).get("qr_string", "")
+                if qr_string:
+                    try:
+                        import qrcode, io, base64
+                        qr = qrcode.QRCode(border=1)
+                        qr.add_data(qr_string)
+                        qr.make(fit=True)
+                        img = qr.make_image(fill_color="black", back_color="white")
+                        buf = io.BytesIO()
+                        img.save(buf, format="PNG")
+                        qr_data = f"data:image/png;base64,{base64.b64encode(buf.getvalue()).decode()}"
+                    except Exception as e:
+                        logger.warning(f"Failed to generate QR image: {e}")
+
+            if not qr_data:
+                await bridge.stop()
+                return {"success": False, "status": "error", "message": "Failed to generate QR code."}
+            if qr_data and not qr_data.startswith("data:"):
+                qr_data = f"data:image/png;base64,{qr_data}"
+
+            session_id = "bridge"
+            _qr_sessions[session_id] = bridge
+            return {
+                "success": True, "session_id": session_id, "qr_code": qr_data,
+                "status": "qr_ready", "message": "Scan the QR code with your WhatsApp mobile app",
+            }
+
+        await bridge.stop()
+        return {"success": False, "status": "error", "message": "Timed out waiting for WhatsApp bridge."}
+    except Exception as e:
+        logger.error(f"Failed to start WhatsApp QR session: {e}")
+        return {"success": False, "status": "error", "message": f"Failed to start session: {e}"}
+
+
+async def check_qr_session_status(session_id: str) -> Dict[str, Any]:
+    """Poll a started QR session. On ``connected`` it saves the credential
+    and starts the platform listener if a manager is running."""
+    bridge = _qr_sessions.get(session_id)
+    if bridge is None:
+        return {"success": False, "status": "error", "connected": False,
+                "message": "Session not found. Please start a new session."}
+
+    try:
+        if bridge.is_ready:
+            try:
+                owner_phone = bridge.owner_phone or ""
+                owner_name = bridge.owner_name or ""
+                save_credential(WHATSAPP_WEB.cred_file, WhatsAppWebCredential(
+                    session_id="bridge", owner_phone=owner_phone, owner_name=owner_name,
+                ))
+                del _qr_sessions[session_id]
+
+                # Best-effort: start the listener if a manager is running.
+                try:
+                    from ...manager import get_external_comms_manager
+                    manager = get_external_comms_manager()
+                    if manager:
+                        await manager.start_platform(WHATSAPP_WEB.platform_id)
+                except Exception:
+                    pass
+
+                display = owner_phone or owner_name or "connected"
+                return {"success": True, "status": "connected", "connected": True,
+                        "message": f"WhatsApp connected: +{display}"}
+            except Exception as e:
+                logger.error(f"Failed to store WhatsApp credential: {e}")
+                return {"success": False, "status": "error", "connected": False,
+                        "message": f"Connected but failed to save: {e}"}
+        elif not bridge.is_running:
+            if session_id in _qr_sessions:
+                del _qr_sessions[session_id]
+            return {"success": False, "status": "error", "connected": False,
+                    "message": "WhatsApp bridge stopped unexpectedly. Please try again."}
+        else:
+            return {"success": True, "status": "qr_ready", "connected": False,
+                    "message": "Waiting for QR code scan..."}
+    except Exception as e:
+        logger.error(f"Failed to check WhatsApp session status: {e}")
+        return {"success": False, "status": "error", "connected": False,
+                "message": f"Status check failed: {e}"}
+
+
+def cancel_qr_session(session_id: str) -> Dict[str, Any]:
+    bridge = _qr_sessions.pop(session_id, None)
+    if bridge is not None:
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                asyncio.ensure_future(bridge.stop())
+            else:
+                loop.run_until_complete(bridge.stop())
+        except Exception:
+            pass
+        return {"success": True, "message": "Session cancelled."}
+    return {"success": True, "message": "Session not found or already cancelled."}
diff --git a/app/external_comms/platforms/whatsapp_bridge/client.py b/craftos_integrations/integrations/whatsapp_web/_bridge_client.py
similarity index 56%
rename from app/external_comms/platforms/whatsapp_bridge/client.py
rename to craftos_integrations/integrations/whatsapp_web/_bridge_client.py
index 905d7f40..7d969cae 100644
--- a/app/external_comms/platforms/whatsapp_bridge/client.py
+++ b/craftos_integrations/integrations/whatsapp_web/_bridge_client.py
@@ -1,47 +1,31 @@
 # -*- coding: utf-8 -*-
-"""
-Python client for the WhatsApp Node.js bridge process.
+"""Python client for the WhatsApp Node.js bridge process.
 
 Manages the Node.js subprocess lifecycle and provides an async API for
 sending commands and receiving events via stdin/stdout JSON lines.
 """
-
 from __future__ import annotations
 
 import asyncio
 import json
-import logging
 import os
 import subprocess
-import sys
 import uuid
 from pathlib import Path
-from typing import Any, Callable, Coroutine, Dict, List, Optional
+from typing import Any, Callable, Coroutine, Dict, Optional
 
-try:
-    from app.logger import logger
-except Exception:
-    logger = logging.getLogger(__name__)
-    logging.basicConfig(level=logging.INFO)
+from ...config import ConfigStore
+from ...logger import get_logger
+
+logger = get_logger(__name__)
 
-# Path to the bridge.js script
 BRIDGE_DIR = Path(__file__).parent
 BRIDGE_SCRIPT = BRIDGE_DIR / "bridge.js"
 
-# Type alias for event callbacks
 EventCallback = Callable[[str, Dict[str, Any]], Coroutine[Any, Any, None]]
 
 
 class WhatsAppBridge:
-    """
-    Manages a whatsapp-web.js Node.js subprocess.
-
-    Communication:
-      - Commands are sent as JSON lines to the subprocess stdin.
-      - Events and responses are read as JSON lines from stdout.
-      - Logs from the bridge go to stderr (forwarded to Python logger).
-    """
-
     def __init__(self, auth_dir: Optional[str] = None):
         self._process: Optional[asyncio.subprocess.Process] = None
         self._reader_task: Optional[asyncio.Task] = None
@@ -57,9 +41,7 @@ def __init__(self, auth_dir: Optional[str] = None):
         if auth_dir:
             self._auth_dir = auth_dir
         else:
-            # Default: .credentials/whatsapp_wwebjs_auth relative to project root
-            project_root = Path(__file__).parent.parent.parent.parent.parent
-            self._auth_dir = str(project_root / ".credentials" / "whatsapp_wwebjs_auth")
+            self._auth_dir = str(ConfigStore.project_root / ".credentials" / "whatsapp_wwebjs_auth")
 
     @property
     def is_running(self) -> bool:
@@ -77,45 +59,125 @@ def owner_phone(self) -> str:
     def owner_name(self) -> str:
         return self._owner_name
 
-    def set_event_callback(self, callback: EventCallback) -> None:
-        """Set the callback for bridge events (message, qr, ready, etc.)."""
+    def set_event_callback(self, callback: Optional[EventCallback]) -> None:
         self._event_callback = callback
 
-    # ------------------------------------------------------------------
-    # Lifecycle
-    # ------------------------------------------------------------------
+    def _clear_stale_session_locks(self) -> None:
+        """Best-effort cleanup of orphaned Chromium state in the auth dir.
+
+        wwebjs uses Puppeteer to launch a Chromium pinned to ``auth_dir``.
+        If the agent or the Node bridge is killed without going through
+        ``client.destroy()``, Chromium leaves singleton lock files behind
+        and (on Windows) the ``chrome.exe`` child process can outlive its
+        Node parent. The next bridge launch then fails with
+        "The browser is already running for ..." because Chromium thinks
+        another instance owns the directory.
+
+        We:
+          1. Find any orphan Chromium processes whose ``--user-data-dir``
+             argument resolves to OUR auth directory, and kill them.
+          2. Remove all known singleton/lock files Chromium leaves
+             (``SingletonLock``, ``SingletonSocket``, ``SingletonCookie``,
+             ``lockfile`` etc.) under the session subdirectory.
+
+        Matched by absolute path, not basename, so we don't kill unrelated
+        Chrome processes.
+        """
+        auth_dir = Path(self._auth_dir).resolve()
+        session_dir = auth_dir / "session"
+        # Substring used to match the auth dir anywhere in a Chromium
+        # process's command line. We deliberately avoid ``Path.resolve()``
+        # equality on Windows because puppeteer launches some children
+        # with the path quoted, some unquoted, some with a trailing
+        # backslash, and ``Path.resolve()`` does not always round-trip
+        # — every miss leaks another zombie tree.
+        auth_dir_marker = str(auth_dir).lower()
+
+        # 1. Kill orphan Chromium processes pinned to our auth dir
+        killed = 0
+        try:
+            import psutil  # type: ignore[import-untyped]
+            for proc in psutil.process_iter(attrs=["pid", "name", "cmdline"]):
+                try:
+                    name = (proc.info.get("name") or "").lower()
+                    if name not in ("chrome.exe", "chrome", "chromium", "chromium.exe"):
+                        continue
+                    cmdline = proc.info.get("cmdline") or []
+                    if not cmdline:
+                        continue
+                    joined = " ".join(a for a in cmdline if isinstance(a, str)).lower()
+                    if auth_dir_marker not in joined:
+                        continue
+                    proc.kill()
+                    killed += 1
+                except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
+                    continue
+        except ImportError:
+            # No psutil — fall back to taskkill on Windows. Best-effort
+            # match on the full path string in command line.
+            if os.name == "nt":
+                try:
+                    subprocess.run(
+                        ["taskkill", "/F", "/IM", "chrome.exe",
+                         "/FI", f"WINDOWTITLE eq *{session_dir.name}*"],
+                        capture_output=True, timeout=5,
+                    )
+                except Exception:
+                    pass
+
+        # 2. Delete singleton/lock files. Chromium creates these in the
+        # user-data-dir at every launch and uses them to detect
+        # already-running instances.
+        lock_names = (
+            "SingletonLock", "SingletonSocket", "SingletonCookie",
+            "lockfile", "Singleton",
+        )
+        removed = 0
+        for name in lock_names:
+            f = session_dir / name
+            try:
+                if f.is_symlink() or f.exists():
+                    f.unlink(missing_ok=True)
+                    removed += 1
+            except Exception as e:
+                logger.debug(f"[WA-Bridge] could not remove {f}: {e}")
+
+        if killed or removed:
+            logger.info(
+                f"[WA-Bridge] cleared stale session state "
+                f"(killed {killed} orphan Chromium proc(s), removed {removed} lock file(s))"
+            )
+
+    def _wipe_orphan_localauth_if_disconnected(self) -> None:
+        """Defense-in-depth: if the user's top-level credential file is gone
+        but wwebjs's LocalAuth data still exists, the user has disconnected
+        but the logout RPC didn't finish wiping the session before reconnect.
+        Force-wipe the auth dir so the next connect demands a fresh QR
+        instead of silently restoring the stale session.
+        """
+        import shutil
+        cred_path = Path(ConfigStore.project_root) / ".credentials" / "whatsapp_web.json"
+        auth_path = Path(self._auth_dir)
+        if cred_path.exists():
+            return  # User is still connected; LocalAuth is legitimate.
+        if not auth_path.exists():
+            return  # Already clean.
+        try:
+            shutil.rmtree(auth_path, ignore_errors=True)
+            logger.info(
+                "[WA-Bridge] wiped orphan LocalAuth — credential was removed "
+                "but session data remained; forcing fresh QR on this connect"
+            )
+        except Exception as e:
+            logger.warning(f"[WA-Bridge] could not wipe orphan LocalAuth: {e}")
 
     async def start(self) -> None:
-        """Start the Node.js bridge subprocess."""
         if self.is_running:
-            logger.warning("[WA-Bridge] Already running")
             return
 
-        # Kill any stale Chromium processes using the wwebjs auth directory
-        auth_dir = Path(self._auth_dir)
-        if os.name == "nt":
-            try:
-                # Find and kill chrome processes with our auth dir in command line
-                result = subprocess.run(
-                    ["wmic", "process", "where", f"commandline like '%{auth_dir.name}%' and name='chrome.exe'", "get", "processid"],
-                    capture_output=True, text=True, timeout=5,
-                )
-                for line in result.stdout.strip().split("\n")[1:]:
-                    pid = line.strip()
-                    if pid.isdigit():
-                        subprocess.run(["taskkill", "/F", "/PID", pid], capture_output=True, timeout=5)
-                        logger.info(f"[WA-Bridge] Killed stale Chromium process: {pid}")
-            except Exception:
-                pass
-        # Also clean lock file
-        lock_file = auth_dir / "session" / "SingletonLock"
-        if lock_file.exists():
-            try:
-                lock_file.unlink(missing_ok=True)
-            except Exception:
-                pass
+        self._clear_stale_session_locks()
+        self._wipe_orphan_localauth_if_disconnected()
 
-        # Ensure node_modules are installed
         node_modules = BRIDGE_DIR / "node_modules"
         if not node_modules.exists():
             logger.info("[WA-Bridge] Installing npm dependencies...")
@@ -131,7 +193,7 @@ async def start(self) -> None:
                 stderr = await proc.stderr.read()
                 raise RuntimeError(f"npm install failed: {stderr.decode()}")
 
-        logger.info(f"[WA-Bridge] Starting bridge process (auth_dir={self._auth_dir})")
+        logger.info(f"[WA-Bridge] Starting bridge (auth_dir={self._auth_dir})")
 
         node_cmd = "node.exe" if os.name == "nt" else "node"
         self._process = await asyncio.create_subprocess_exec(
@@ -144,31 +206,58 @@ async def start(self) -> None:
         self._running = True
         self._reader_task = asyncio.create_task(self._read_stdout())
         self._stderr_task = asyncio.create_task(self._read_stderr())
-        logger.info(f"[WA-Bridge] Process started (pid={self._process.pid})")
 
     async def stop(self) -> None:
-        """Gracefully stop the bridge subprocess."""
+        await self._teardown(cmd="shutdown")
+
+    async def logout(self) -> None:
+        """Full disconnect — fire-and-forget, with a tight timeout.
+
+        wwebjs's ``client.logout()`` can hang for 30+ seconds on a stuck
+        session because it tries to flush the WhatsApp server-side
+        invalidation through a half-broken connection. Waiting for that
+        gives terrible UX (user clicks Disconnect → 2 minutes of silence).
+
+        Trade-off: we give Node ~3s to start the server-side logout, then
+        force-kill the process and wipe LocalAuth ourselves. The user's
+        local state (no cred, no auth dir) is the source-of-truth for
+        "disconnected"; WhatsApp will eventually expire the server session
+        on its own. Net effect: disconnect feels instant, fresh QR every
+        reconnect.
+        """
+        await self._teardown(cmd="logout", send_timeout=3.0, wait_timeout=3.0)
+        from pathlib import Path
+        import shutil
+        try:
+            shutil.rmtree(Path(self._auth_dir), ignore_errors=True)
+        except Exception as e:
+            logger.warning(f"[WA-Bridge] could not remove auth dir: {e}")
+
+    async def _teardown(
+        self,
+        cmd: str = "shutdown",
+        send_timeout: float = 10.0,
+        wait_timeout: float = 20.0,
+    ) -> None:
+        """Send ``cmd`` to the bridge, wait for the Node process to exit,
+        and clean up reader tasks. Used by both ``stop`` and ``logout``.
+        Tighter timeouts give logout a snappy UX; ``stop`` keeps the
+        original generous timeouts for graceful agent-shutdown paths."""
         if not self.is_running:
             return
-
-        logger.info("[WA-Bridge] Stopping bridge...")
         self._running = False
         self._ready = False
 
-        # Send shutdown command — give wwebjs time to save session
         try:
-            await self.send_command("shutdown", timeout=10.0)
+            await self.send_command(cmd, timeout=send_timeout)
         except Exception:
             pass
 
-        # Wait for graceful exit — wwebjs needs time to save session files
         if self._process:
             try:
-                await asyncio.wait_for(self._process.wait(), timeout=20.0)
+                await asyncio.wait_for(self._process.wait(), timeout=wait_timeout)
             except asyncio.TimeoutError:
-                logger.warning("[WA-Bridge] Process did not exit, killing process tree")
                 if os.name == "nt":
-                    # Windows: kill entire process tree (including spawned Chromium)
                     try:
                         subprocess.run(
                             ["taskkill", "/F", "/T", "/PID", str(self._process.pid)],
@@ -179,7 +268,6 @@ async def stop(self) -> None:
                 else:
                     self._process.kill()
 
-        # Cancel reader tasks
         for task in [self._reader_task, self._stderr_task]:
             if task and not task.done():
                 task.cancel()
@@ -192,25 +280,13 @@ async def stop(self) -> None:
         self._reader_task = None
         self._stderr_task = None
 
-        # Resolve pending futures with errors
         for req_id, future in self._pending.items():
             if not future.done():
                 future.set_exception(RuntimeError("Bridge stopped"))
         self._pending.clear()
 
-        logger.info("[WA-Bridge] Bridge stopped")
-
-    # ------------------------------------------------------------------
-    # Commands
-    # ------------------------------------------------------------------
-
-    async def send_command(
-        self,
-        cmd: str,
-        args: Optional[Dict[str, Any]] = None,
-        timeout: float = 30.0,
-    ) -> Dict[str, Any]:
-        """Send a command to the bridge and wait for the response."""
+    async def send_command(self, cmd: str, args: Optional[Dict[str, Any]] = None,
+                           timeout: float = 30.0) -> Dict[str, Any]:
         if not self.is_running:
             raise RuntimeError("Bridge not running")
 
@@ -232,35 +308,24 @@ async def send_command(
             raise
 
     async def send_message(self, to: str, text: str) -> Dict[str, Any]:
-        """Send a text message."""
         return await self.send_command("send_message", {"to": to, "text": text})
 
     async def get_status(self) -> Dict[str, Any]:
-        """Get bridge/client status."""
         return await self.send_command("get_status")
 
     async def get_chats(self, limit: int = 50) -> Dict[str, Any]:
-        """Get recent chats."""
         return await self.send_command("get_chats", {"limit": limit})
 
     async def get_chat_messages(self, chat_id: str, limit: int = 50) -> Dict[str, Any]:
-        """Get messages from a chat."""
         return await self.send_command("get_chat_messages", {"chat_id": chat_id, "limit": limit})
 
     async def search_contact(self, name: str) -> Dict[str, Any]:
-        """Search contacts by name."""
         return await self.send_command("search_contact", {"name": name})
 
     async def get_unread_chats(self) -> Dict[str, Any]:
-        """Get chats with unread messages."""
         return await self.send_command("get_unread_chats")
 
-    # ------------------------------------------------------------------
-    # Wait helpers
-    # ------------------------------------------------------------------
-
     async def wait_for_ready(self, timeout: float = 120.0) -> bool:
-        """Wait until the bridge reports 'ready' (connected to WhatsApp)."""
         deadline = asyncio.get_event_loop().time() + timeout
         while asyncio.get_event_loop().time() < deadline:
             if self._ready:
@@ -271,11 +336,6 @@ async def wait_for_ready(self, timeout: float = 120.0) -> bool:
         return False
 
     async def wait_for_qr_or_ready(self, timeout: float = 120.0):
-        """
-        Wait until either a QR code is emitted or client becomes ready.
-        Returns ("ready", data) or ("qr", data) or ("timeout", None).
-        """
-        # If already ready, return immediately
         if self._ready:
             return "ready", {
                 "owner_phone": self._owner_phone,
@@ -285,7 +345,6 @@ async def wait_for_qr_or_ready(self, timeout: float = 120.0):
 
         event_received = asyncio.Event()
         result = {"type": None, "data": None}
-
         original_callback = self._event_callback
 
         async def intercept_callback(event: str, data: dict):
@@ -305,12 +364,7 @@ async def intercept_callback(event: str, data: dict):
         finally:
             self._event_callback = original_callback
 
-    # ------------------------------------------------------------------
-    # Internal: stdout/stderr readers
-    # ------------------------------------------------------------------
-
     async def _read_stdout(self) -> None:
-        """Read JSON lines from the bridge stdout."""
         try:
             while self._running and self._process and self._process.stdout:
                 line = await self._process.stdout.readline()
@@ -319,33 +373,27 @@ async def _read_stdout(self) -> None:
                 try:
                     data = json.loads(line.decode().strip())
                 except json.JSONDecodeError:
-                    logger.debug(f"[WA-Bridge] Non-JSON stdout: {line.decode().strip()}")
                     continue
 
                 msg_type = data.get("type")
-
                 if msg_type == "response":
                     req_id = data.get("id")
                     future = self._pending.pop(req_id, None)
                     if future and not future.done():
                         future.set_result(data.get("data", {}))
-
                 elif msg_type == "event":
                     event = data.get("event", "")
                     event_data = data.get("data", {})
                     self._handle_event(event, event_data)
-
         except asyncio.CancelledError:
             pass
         except Exception as e:
             logger.error(f"[WA-Bridge] stdout reader error: {e}")
         finally:
             if self._running:
-                logger.warning("[WA-Bridge] stdout reader exited unexpectedly")
                 self._ready = False
 
     async def _read_stderr(self) -> None:
-        """Forward bridge stderr to Python logger."""
         try:
             while self._running and self._process and self._process.stderr:
                 line = await self._process.stderr.readline()
@@ -356,59 +404,26 @@ async def _read_stderr(self) -> None:
                     logger.info(f"[WA-Bridge:node] {text}")
         except asyncio.CancelledError:
             pass
-        except Exception as e:
-            logger.debug(f"[WA-Bridge] stderr reader error: {e}")
+        except Exception:
+            pass
 
     def _handle_event(self, event: str, data: Dict[str, Any]) -> None:
-        """Process an event from the bridge."""
         if event == "ready":
             self._ready = True
             self._owner_phone = data.get("owner_phone", "")
             self._owner_name = data.get("owner_name", "")
             self._wid = data.get("wid", "")
-            logger.info(
-                f"[WA-Bridge] Ready: phone={self._owner_phone}, "
-                f"name={self._owner_name}, wid={self._wid}"
-            )
-
         elif event == "disconnected":
             self._ready = False
-            logger.warning(f"[WA-Bridge] Disconnected: {data.get('reason', 'unknown')}")
-
-        elif event == "message":
-            logger.info(
-                f"[WA-Bridge] Message from {data.get('contact', {}).get('name', 'unknown')} "
-                f"in {data.get('chat', {}).get('name', 'unknown')}: "
-                f"{(data.get('body', '') or '')[:80]}"
-            )
-
-        elif event == "message_sent":
-            logger.info(
-                f"[WA-Bridge] Message sent to {data.get('chat', {}).get('name', 'unknown')} "
-                f"(self_chat={data.get('is_self_chat', False)}): "
-                f"{(data.get('body', '') or '')[:80]}"
-            )
 
-        elif event == "qr":
-            logger.info("[WA-Bridge] QR code received (waiting for scan)")
-
-        elif event == "auth_failure":
-            logger.error(f"[WA-Bridge] Auth failure: {data.get('message', '')}")
-
-        # Dispatch to callback
         if self._event_callback:
             asyncio.ensure_future(self._event_callback(event, data))
 
 
-# ---------------------------------------------------------------------------
-# Module-level singleton
-# ---------------------------------------------------------------------------
-
 _bridge_instance: Optional[WhatsAppBridge] = None
 
 
 def get_whatsapp_bridge() -> WhatsAppBridge:
-    """Get or create the global WhatsAppBridge singleton."""
     global _bridge_instance
     if _bridge_instance is None:
         _bridge_instance = WhatsAppBridge()
diff --git a/app/external_comms/platforms/whatsapp_bridge/bridge.js b/craftos_integrations/integrations/whatsapp_web/bridge.js
similarity index 50%
rename from app/external_comms/platforms/whatsapp_bridge/bridge.js
rename to craftos_integrations/integrations/whatsapp_web/bridge.js
index 7de06fe8..93befa84 100644
--- a/app/external_comms/platforms/whatsapp_bridge/bridge.js
+++ b/craftos_integrations/integrations/whatsapp_web/bridge.js
@@ -56,21 +56,44 @@ log(`Auth directory: ${AUTH_DIR}`);
 // WhatsApp Client
 // ---------------------------------------------------------------------------
 
-const client = new Client({
-  authStrategy: new LocalAuth({ dataPath: AUTH_DIR }),
-  puppeteer: {
-    headless: true,
-    protocolTimeout: 120000,
-    args: [
-      "--no-sandbox",
-      "--disable-setuid-sandbox",
-      "--disable-dev-shm-usage",
-      "--disable-gpu",
-      "--disable-extensions",
-      "--disable-background-timer-throttling",
-    ],
-  },
-});
+// We deliberately do NOT pin a webVersionCache. Pinning ties us to a
+// snapshot from wppconnect-team/wa-version, which (a) prunes old entries
+// after a few months → 404 → ``Runtime.callFunctionOn timed out`` during
+// init, and (b) drifts away from whatever wwebjs's internal selectors
+// actually expect → ``authenticated`` fires but ``ready`` never does, so
+// the synthetic-ready fallback kicks in but messages don't actually flow
+// because wwebjs's internal listeners haven't attached.
+//
+// Without webVersionCache, wwebjs loads web.whatsapp.com directly, using
+// the same JS that the user's actual browser uses. That tracks WhatsApp's
+// current build and matches wwebjs's selectors most reliably. If a future
+// WhatsApp update breaks wwebjs's selectors, the fix is to bump the
+// ``whatsapp-web.js`` package version, not to re-introduce a pinned HTML
+// that will go stale a few months later.
+
+// ``client`` is module-level + ``let`` (not ``const``) so the watchdog/retry
+// path can replace it with a fresh instance after a stuck-init recovery.
+// Command handlers below reference ``client`` lazily — they always pick up
+// the current binding.
+let client;
+
+function buildClient() {
+  return new Client({
+    authStrategy: new LocalAuth({ dataPath: AUTH_DIR }),
+    puppeteer: {
+      headless: true,
+      protocolTimeout: 120000,
+      args: [
+        "--no-sandbox",
+        "--disable-setuid-sandbox",
+        "--disable-dev-shm-usage",
+        "--disable-gpu",
+        "--disable-extensions",
+        "--disable-background-timer-throttling",
+      ],
+    },
+  });
+}
 
 // Track message IDs sent by us so we can skip them in message_create
 const ownSentIds = new Set();
@@ -85,7 +108,12 @@ let selfChatId = "";
 // Client Events
 // ---------------------------------------------------------------------------
 
-client.on("qr", async (qr) => {
+// Attach all wwebjs event handlers to ``c``. Called once per buildClient() —
+// the watchdog/retry path re-runs this against the freshly built client so
+// every retry has the same wiring.
+function attachHandlers(c) {
+
+c.on("qr", async (qr) => {
   log("QR code received");
   try {
     const dataUrl = await qrcode.toDataURL(qr);
@@ -95,17 +123,59 @@ client.on("qr", async (qr) => {
   }
 });
 
-client.on("authenticated", () => {
+c.on("authenticated", () => {
   log("Authenticated");
+  authedThisAttempt = true;
+  if (initWatchdog) { clearTimeout(initWatchdog); initWatchdog = null; }
   emitEvent("authenticated");
+
+  // Ready-watchdog: when wwebjs's selectors drift from what WhatsApp's
+  // current bundle exposes, ``authenticated`` fires but ``ready`` never
+  // does — and crucially wwebjs's internal message listeners don't attach,
+  // so messages don't flow. We wait 60s for the real ``ready``; if it
+  // doesn't arrive, we treat it as a stuck-init failure and reuse the
+  // existing watchdog/retry path (destroy → rebuild → reinitialize).
+  // Only after the retry budget is exhausted do we fall through to a
+  // synthetic ``ready`` so sends still work — receive will be broken in
+  // that fallback state, but the bridge is at least usable for outbound.
+  setTimeout(async () => {
+    if (isReady) return;
+    if (initAttempt <= MAX_INIT_RETRIES) {
+      log(`'ready' not received within 60s of authenticated — treating as stuck init, retrying (attempt ${initAttempt}/${MAX_INIT_RETRIES + 1})`);
+      initAttempt += 1;
+      try { await client.destroy(); } catch (err) { log(`destroy during ready-retry: ${err.message}`); }
+      client = buildClient();
+      attachHandlers(client);
+      authedThisAttempt = false;
+      startClientWithWatchdog();
+      return;
+    }
+    // Retry budget exhausted — fall through to synthetic so sends still work.
+    log("'ready' not received and retries exhausted — synthesizing (sends only, receive will not work)");
+    try {
+      if (client.info && client.info.wid) {
+        ownerPhone = client.info.wid.user || ownerPhone;
+        ownerName = client.info.pushname || ownerName;
+      }
+    } catch (_) { /* best-effort */ }
+    isReady = true;
+    readyTimestamp = Math.floor(Date.now() / 1000);
+    emitEvent("ready", {
+      owner_phone: ownerPhone,
+      owner_name: ownerName,
+      wid: client.info?.wid?._serialized || "",
+      synthetic: true,
+    });
+    emitEvent("error", { message: "ready event never fired — message receive will not work. Try restarting the agent or updating whatsapp-web.js.", fatal: false });
+  }, 60_000);
 });
 
-client.on("auth_failure", (msg) => {
+c.on("auth_failure", (msg) => {
   log(`Auth failure: ${msg}`);
   emitEvent("auth_failure", { message: String(msg) });
 });
 
-client.on("ready", async () => {
+c.on("ready", async () => {
   isReady = true;
   readyTimestamp = Math.floor(Date.now() / 1000);
   log("Client ready");
@@ -161,7 +231,7 @@ client.on("ready", async () => {
   }
 });
 
-client.on("disconnected", (reason) => {
+c.on("disconnected", (reason) => {
   isReady = false;
   catchupDone = false;
   readyTimestamp = 0;
@@ -173,7 +243,7 @@ client.on("disconnected", (reason) => {
 // Message Events
 // ---------------------------------------------------------------------------
 
-client.on("message", async (msg) => {
+c.on("message", async (msg) => {
   // Skip messages from before the bridge was ready (historical sync)
   if (msg.timestamp && msg.timestamp < readyTimestamp) return;
 
@@ -210,7 +280,7 @@ client.on("message", async (msg) => {
   }
 });
 
-client.on("message_create", async (msg) => {
+c.on("message_create", async (msg) => {
   // Skip messages from before the bridge was ready (historical sync)
   if (msg.timestamp && msg.timestamp < readyTimestamp) return;
   if (!msg.fromMe) return;
@@ -246,6 +316,73 @@ client.on("message_create", async (msg) => {
   }
 });
 
+}  // end attachHandlers(c)
+
+// ---------------------------------------------------------------------------
+// Init watchdog + retry — auto-recovers from "stuck before authenticated"
+//
+// Failure mode this protects against: wwebjs's ``client.initialize()`` hangs
+// for 2+ minutes during the WhatsApp Web page load (most often when the
+// pinned ``webVersionCache`` URL 404s, when leftover Chromium zombies hold
+// the auth dir lock, or when WhatsApp pushes a protocol change). The
+// "Initialize error: Runtime.callFunctionOn timed out" we see in logs is
+// puppeteer's protocolTimeout firing on a wwebjs JS call that never returns.
+//
+// Strategy: set a 60s watchdog when initialize() is called. If we don't
+// reach the ``authenticated`` event within that window, kill Chromium with
+// ``client.destroy()``, build a fresh client, re-attach handlers, and
+// re-run initialize. After ``MAX_INIT_RETRIES`` failures we emit a fatal
+// error and exit non-zero so the Python parent can decide what to do (in
+// practice it logs and continues without WhatsApp).
+// ---------------------------------------------------------------------------
+
+const MAX_INIT_RETRIES = 2;
+const INIT_WATCHDOG_MS = 60_000;
+let initAttempt = 0;
+let authedThisAttempt = false;
+let initWatchdog = null;
+
+async function startClientWithWatchdog() {
+  initAttempt += 1;
+  authedThisAttempt = false;
+
+  // Cancel any prior watchdog before arming a new one (defensive — should
+  // already be cleared by the time we get here).
+  if (initWatchdog) clearTimeout(initWatchdog);
+
+  initWatchdog = setTimeout(async () => {
+    if (authedThisAttempt) return;  // raced with the auth event
+    log(`Stuck before 'authenticated' for ${INIT_WATCHDOG_MS / 1000}s — recovering (attempt ${initAttempt})`);
+    if (initAttempt > MAX_INIT_RETRIES) {
+      log(`Max init retries reached — bridge giving up`);
+      emitEvent("error", { message: "WhatsApp bridge stuck before authentication after retries", fatal: true });
+      try { await client.destroy(); } catch (_) {}
+      process.exit(1);
+    }
+    // Tear down the dead Chromium and try fresh
+    try { await client.destroy(); } catch (err) { log(`destroy during retry: ${err.message}`); }
+    client = buildClient();
+    attachHandlers(client);
+    startClientWithWatchdog();
+  }, INIT_WATCHDOG_MS);
+
+  log(`Initializing WhatsApp client... (attempt ${initAttempt}/${MAX_INIT_RETRIES + 1})`);
+  try {
+    await client.initialize();
+  } catch (err) {
+    if (initWatchdog) { clearTimeout(initWatchdog); initWatchdog = null; }
+    log(`Initialize error: ${err.message}`);
+    if (initAttempt > MAX_INIT_RETRIES) {
+      emitEvent("error", { message: err.message, fatal: true });
+      process.exit(1);
+    }
+    try { await client.destroy(); } catch (_) {}
+    client = buildClient();
+    attachHandlers(client);
+    return startClientWithWatchdog();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command Handler (stdin)
 // ---------------------------------------------------------------------------
@@ -268,8 +405,26 @@ async function handleCommand(line) {
           emitResponse(id, { success: false, error: "Client not ready" });
           return;
         }
-        const cleanNum = args.to.replace(/[\s\-\+\(\)]/g, "");
-        const chatId = args.to.includes("@") ? args.to : `${cleanNum}@c.us`;
+        let chatId;
+        if (args.to.includes("@")) {
+          chatId = args.to;
+        } else {
+          // Resolve number → canonical JID via the server. WhatsApp's
+          // LID-based protocol means a locally-constructed `${num}@c.us`
+          // can fail with "No LID for user" for contacts the local Store
+          // has never seen. getNumberId() primes the LID mapping and
+          // also returns null for numbers not on WhatsApp.
+          const cleanNum = args.to.replace(/[\s\-\+\(\)]/g, "");
+          const wid = await client.getNumberId(cleanNum);
+          if (!wid) {
+            emitResponse(id, {
+              success: false,
+              error: `Number ${cleanNum} is not on WhatsApp`,
+            });
+            return;
+          }
+          chatId = wid._serialized;
+        }
         const sent = await client.sendMessage(chatId, args.text);
         if (sent?.id?._serialized) ownSentIds.add(sent.id._serialized);
         emitResponse(id, {
@@ -334,25 +489,74 @@ async function handleCommand(line) {
       }
 
       case "search_contact": {
+        // Strategy: search chats first (fast, robust, covers the
+        // overwhelming case of "find someone I've messaged"). Only if
+        // that returns nothing do we fall back to filtering the full
+        // address book inside the browser page. We can't use
+        // client.getContacts() here — on large accounts the per-contact
+        // RPC serialization exceeds Puppeteer's protocolTimeout.
         if (!isReady) {
           emitResponse(id, { success: false, error: "Client not ready" });
           return;
         }
-        const contacts = await client.getContacts();
         const query = (args.name || "").toLowerCase();
-        const matches = contacts
-          .filter((c) => {
-            const name = (c.pushname || c.name || "").toLowerCase();
-            const number = c.number || "";
+
+        const chats = await client.getChats();
+        let matches = chats
+          .filter((ch) => {
+            const name = (ch.name || "").toLowerCase();
+            const number = (ch.id && ch.id.user) || "";
             return name.includes(query) || number.includes(query);
           })
           .slice(0, 20)
-          .map((c) => ({
-            id: c.id._serialized,
-            name: c.pushname || c.name || "",
-            number: c.number || "",
-            is_group: c.isGroup,
-          }));
+          .map((ch) => {
+            const serialized = ch.id._serialized;
+            // LID-based chats don't have a phone number — ch.id.user is
+            // the LID's user portion, which fails as a `to` value in
+            // send_message. Surface the full JID instead so the agent
+            // round-trips a valid send target through `number`.
+            const isLid = serialized.endsWith("@lid");
+            return {
+              id: serialized,
+              name: ch.name || "",
+              number: isLid ? serialized : ((ch.id && ch.id.user) || ""),
+              is_group: ch.isGroup,
+            };
+          });
+
+        if (matches.length === 0) {
+          // Fallback: reach into the page's Store. Filter runs in-page
+          // so only the matches cross the RPC boundary.
+          try {
+            matches = await client.pupPage.evaluate((q) => {
+              const query = (q || "").toLowerCase();
+              return window.Store.Contact.getModelsArray()
+                .filter((c) => {
+                  const name = (c.pushname || c.name || c.formattedName || "").toLowerCase();
+                  const number = (c.id && c.id.user) || "";
+                  return name.includes(query) || number.includes(query);
+                })
+                .slice(0, 20)
+                .map((c) => {
+                  const serialized = c.id._serialized;
+                  const isLid = serialized.endsWith("@lid");
+                  return {
+                    id: serialized,
+                    name: c.pushname || c.name || c.formattedName || "",
+                    number: isLid ? serialized : ((c.id && c.id.user) || ""),
+                    is_group: c.isGroup,
+                  };
+                });
+            }, args.name || "");
+          } catch (err) {
+            emitResponse(id, {
+              success: false,
+              error: `In-page contact filter failed: ${err.message}`,
+            });
+            return;
+          }
+        }
+
         emitResponse(id, { success: true, contacts: matches });
         break;
       }
@@ -383,6 +587,26 @@ async function handleCommand(line) {
         break;
       }
 
+      case "logout": {
+        // Full disconnect: logs out of WhatsApp server-side AND wipes the
+        // LocalAuth data on disk, so the next connect demands a fresh QR.
+        // Without this, ``client.destroy()`` alone leaves the session
+        // restorable and the bridge auto-reconnects on next start.
+        log("Logout requested");
+        emitResponse(id, { success: true });
+        try {
+          if (client) await client.logout();
+          log("Logged out");
+        } catch (err) {
+          log(`Logout error: ${err.message}`);
+          // Fall through to destroy/exit — even a partial logout is
+          // better than leaving the bridge running.
+          try { if (client) await client.destroy(); } catch (_) {}
+        }
+        process.exit(0);
+        break;
+      }
+
       default:
         emitResponse(id, { success: false, error: `Unknown command: ${cmd}` });
     }
@@ -424,9 +648,8 @@ async function gracefulShutdown() {
 process.on("SIGINT", gracefulShutdown);
 process.on("SIGTERM", gracefulShutdown);
 
-// Start
-log("Initializing WhatsApp client...");
-client.initialize().catch((err) => {
-  log(`Initialize error: ${err.message}`);
-  emitEvent("error", { message: err.message });
-});
+// Start: build the initial client, attach handlers, run with watchdog.
+// startClientWithWatchdog() handles its own retries + final exit on failure.
+client = buildClient();
+attachHandlers(client);
+startClientWithWatchdog();
diff --git a/app/external_comms/platforms/whatsapp_bridge/package-lock.json b/craftos_integrations/integrations/whatsapp_web/package-lock.json
similarity index 71%
rename from app/external_comms/platforms/whatsapp_bridge/package-lock.json
rename to craftos_integrations/integrations/whatsapp_web/package-lock.json
index 496adc60..46f62f96 100644
--- a/app/external_comms/platforms/whatsapp_bridge/package-lock.json
+++ b/craftos_integrations/integrations/whatsapp_web/package-lock.json
@@ -9,7 +9,7 @@
       "version": "1.0.0",
       "dependencies": {
         "qrcode": "^1.5.4",
-        "whatsapp-web.js": "^1.26.1"
+        "whatsapp-web.js": "^1.34.7"
       },
       "engines": {
         "node": ">=18"
@@ -38,11 +38,33 @@
         "node": ">=6.9.0"
       }
     },
-    "node_modules/@pedroslopez/moduleraid": {
-      "version": "5.0.2",
-      "resolved": "https://registry.npmjs.org/@pedroslopez/moduleraid/-/moduleraid-5.0.2.tgz",
-      "integrity": "sha512-wtnBAETBVYZ9GvcbgdswRVSLkFkYAGv1KzwBBTeRXvGT9sb9cPllOgFFWXCn9PyARQ0H+Ijz6mmoRrGateUDxQ==",
-      "license": "MIT"
+    "node_modules/@isaacs/cliui": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
+      "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "string-width": "^5.1.2",
+        "string-width-cjs": "npm:string-width@^4.2.0",
+        "strip-ansi": "^7.0.1",
+        "strip-ansi-cjs": "npm:strip-ansi@^6.0.1",
+        "wrap-ansi": "^8.1.0",
+        "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@pkgjs/parseargs": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz",
+      "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=14"
+      }
     },
     "node_modules/@puppeteer/browsers": {
       "version": "2.13.0",
@@ -65,6 +87,30 @@
         "node": ">=18"
       }
     },
+    "node_modules/@puppeteer/browsers/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@puppeteer/browsers/node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
     "node_modules/@puppeteer/browsers/node_modules/cliui": {
       "version": "8.0.1",
       "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
@@ -79,6 +125,38 @@
         "node": ">=12"
       }
     },
+    "node_modules/@puppeteer/browsers/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/@puppeteer/browsers/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@puppeteer/browsers/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/@puppeteer/browsers/node_modules/wrap-ansi": {
       "version": "7.0.0",
       "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
@@ -139,13 +217,13 @@
       "license": "MIT"
     },
     "node_modules/@types/node": {
-      "version": "25.3.5",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.5.tgz",
-      "integrity": "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA==",
+      "version": "25.6.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
+      "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "undici-types": "~7.18.0"
+        "undici-types": "~7.19.0"
       }
     },
     "node_modules/@types/yauzl": {
@@ -158,6 +236,19 @@
         "@types/node": "*"
       }
     },
+    "node_modules/abort-controller": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz",
+      "integrity": "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "event-target-shim": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=6.5"
+      }
+    },
     "node_modules/agent-base": {
       "version": "7.1.4",
       "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
@@ -168,101 +259,67 @@
       }
     },
     "node_modules/ansi-regex": {
-      "version": "5.0.1",
-      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
-      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+      "integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
       "license": "MIT",
+      "optional": true,
       "engines": {
-        "node": ">=8"
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
       }
     },
     "node_modules/ansi-styles": {
-      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
-      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
       "license": "MIT",
-      "dependencies": {
-        "color-convert": "^2.0.1"
-      },
+      "optional": true,
       "engines": {
-        "node": ">=8"
+        "node": ">=12"
       },
       "funding": {
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
     "node_modules/archiver": {
-      "version": "5.3.2",
-      "resolved": "https://registry.npmjs.org/archiver/-/archiver-5.3.2.tgz",
-      "integrity": "sha512-+25nxyyznAXF7Nef3y0EbBeqmGZgeN/BxHX29Rs39djAfaFalmQ89SE6CWyDCHzGL0yt/ycBtNOmGTW0FyGWNw==",
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/archiver/-/archiver-7.0.1.tgz",
+      "integrity": "sha512-ZcbTaIqJOfCc03QwD468Unz/5Ir8ATtvAHsK+FdXbDIbGfihqh9mrvdcYunQzqn4HrvWWaFyaxJhGZagaJJpPQ==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "archiver-utils": "^2.1.0",
+        "archiver-utils": "^5.0.2",
         "async": "^3.2.4",
-        "buffer-crc32": "^0.2.1",
-        "readable-stream": "^3.6.0",
+        "buffer-crc32": "^1.0.0",
+        "readable-stream": "^4.0.0",
         "readdir-glob": "^1.1.2",
-        "tar-stream": "^2.2.0",
-        "zip-stream": "^4.1.0"
+        "tar-stream": "^3.0.0",
+        "zip-stream": "^6.0.1"
       },
       "engines": {
-        "node": ">= 10"
+        "node": ">= 14"
       }
     },
     "node_modules/archiver-utils": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/archiver-utils/-/archiver-utils-2.1.0.tgz",
-      "integrity": "sha512-bEL/yUb/fNNiNTuUz979Z0Yg5L+LzLxGJz8x79lYmR54fmTIb6ob/hNQgkQnIUDWIFjZVQwl9Xs356I6BAMHfw==",
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/archiver-utils/-/archiver-utils-5.0.2.tgz",
+      "integrity": "sha512-wuLJMmIBQYCsGZgYLTy5FIB2pF6Lfb6cXMSF8Qywwk3t20zWnAi7zLcQFdKQmIB8wyZpY5ER38x08GbwtR2cLA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "glob": "^7.1.4",
+        "glob": "^10.0.0",
         "graceful-fs": "^4.2.0",
+        "is-stream": "^2.0.1",
         "lazystream": "^1.0.0",
-        "lodash.defaults": "^4.2.0",
-        "lodash.difference": "^4.5.0",
-        "lodash.flatten": "^4.4.0",
-        "lodash.isplainobject": "^4.0.6",
-        "lodash.union": "^4.6.0",
+        "lodash": "^4.17.15",
         "normalize-path": "^3.0.0",
-        "readable-stream": "^2.0.0"
+        "readable-stream": "^4.0.0"
       },
       "engines": {
-        "node": ">= 6"
-      }
-    },
-    "node_modules/archiver-utils/node_modules/readable-stream": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
-      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "core-util-is": "~1.0.0",
-        "inherits": "~2.0.3",
-        "isarray": "~1.0.0",
-        "process-nextick-args": "~2.0.0",
-        "safe-buffer": "~5.1.1",
-        "string_decoder": "~1.1.1",
-        "util-deprecate": "~1.0.1"
-      }
-    },
-    "node_modules/archiver-utils/node_modules/safe-buffer": {
-      "version": "5.1.2",
-      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
-      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/archiver-utils/node_modules/string_decoder": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
-      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "safe-buffer": "~5.1.0"
+        "node": ">= 14"
       }
     },
     "node_modules/argparse": {
@@ -291,9 +348,9 @@
       "optional": true
     },
     "node_modules/b4a": {
-      "version": "1.8.0",
-      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.0.tgz",
-      "integrity": "sha512-qRuSmNSkGQaHwNbM7J78Wwy+ghLEYF1zNrSeMxj4Kgw6y33O3mXcQ6Ie9fRvfU/YnxWkOchPXbaLb73TkIsfdg==",
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.1.tgz",
+      "integrity": "sha512-aiqre1Nr0B/6DgE2N5vwTc+2/oQZ4Wh1t4NznYY4E00y8LCt6NqdRv81so00oo27D8MVKTpUa/MwUUtBLXCoDw==",
       "license": "Apache-2.0",
       "peerDependencies": {
         "react-native-b4a": "*"
@@ -326,9 +383,9 @@
       }
     },
     "node_modules/bare-fs": {
-      "version": "4.5.5",
-      "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-4.5.5.tgz",
-      "integrity": "sha512-XvwYM6VZqKoqDll8BmSww5luA5eflDzY0uEFfBJtFKe4PAAtxBjU3YIxzIBzhyaEQBy1VXEQBto4cpN5RZJw+w==",
+      "version": "4.7.1",
+      "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-4.7.1.tgz",
+      "integrity": "sha512-WDRsyVN52eAx/lBamKD6uyw8H4228h/x0sGGGegOamM2cd7Pag88GfMQalobXI+HaEUxpCkbKQUDOQqt9wawRw==",
       "license": "Apache-2.0",
       "dependencies": {
         "bare-events": "^2.5.4",
@@ -350,9 +407,9 @@
       }
     },
     "node_modules/bare-os": {
-      "version": "3.7.1",
-      "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.7.1.tgz",
-      "integrity": "sha512-ebvMaS5BgZKmJlvuWh14dg9rbUI84QeV3WlWn6Ph6lFI8jJoh7ADtVTyD2c93euwbe+zgi0DVrl4YmqXeM9aIA==",
+      "version": "3.9.1",
+      "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.9.1.tgz",
+      "integrity": "sha512-6M5XjcnsygQNPMCMPXSK379xrJFiZ/AEMNBmFEmQW8d/789VQATvriyi5r0HYTL9TkQ26rn3kgdTG3aisbrXkQ==",
       "license": "Apache-2.0",
       "engines": {
         "bare": ">=1.14.0"
@@ -368,19 +425,23 @@
       }
     },
     "node_modules/bare-stream": {
-      "version": "2.8.0",
-      "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.8.0.tgz",
-      "integrity": "sha512-reUN0M2sHRqCdG4lUK3Fw8w98eeUIZHL5c3H7Mbhk2yVBL+oofgaIp0ieLfD5QXwPCypBpmEEKU2WZKzbAk8GA==",
+      "version": "2.13.1",
+      "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.13.1.tgz",
+      "integrity": "sha512-Vp0cnjYyrEC4whYTymQ+YZi6pBpfiICZO3cfRG8sy67ZNWe951urv1x4eW1BKNngw3U+3fPYb5JQvHbCtxH7Ow==",
       "license": "Apache-2.0",
       "dependencies": {
-        "streamx": "^2.21.0",
+        "streamx": "^2.25.0",
         "teex": "^1.0.1"
       },
       "peerDependencies": {
+        "bare-abort-controller": "*",
         "bare-buffer": "*",
         "bare-events": "*"
       },
       "peerDependenciesMeta": {
+        "bare-abort-controller": {
+          "optional": true
+        },
         "bare-buffer": {
           "optional": true
         },
@@ -390,9 +451,9 @@
       }
     },
     "node_modules/bare-url": {
-      "version": "2.3.2",
-      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.3.2.tgz",
-      "integrity": "sha512-ZMq4gd9ngV5aTMa5p9+UfY0b3skwhHELaDkhEHetMdX0LRkW9kzaym4oo/Eh+Ghm0CCDuMTsRIGM/ytUc1ZYmw==",
+      "version": "2.4.3",
+      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.4.3.tgz",
+      "integrity": "sha512-Kccpc7ACfXaxfeInfqKcZtW4pT5YBn1mesc4sCsun6sRwtbJ4h+sNOaksUpYEJUKfN65YWC6Bw2OJEFiKxq8nQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "bare-path": "^3.0.0"
@@ -420,72 +481,35 @@
       "optional": true
     },
     "node_modules/basic-ftp": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.0.tgz",
-      "integrity": "sha512-VoMINM2rqJwJgfdHq6RiUudKt2BV+FY5ZFezP/ypmwayk68+NzzAQy4XXLlqsGD4MCzq3DrmNFD/uUmBJuGoXw==",
+      "version": "5.3.1",
+      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.3.1.tgz",
+      "integrity": "sha512-bopVNp6ugyA150DDuZfPFdt1KZ5a94ZDiwX4hMgZDzF+GttD80lEy8kj98kbyhLXnPvhtIo93mdnLIjpCAeeOw==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
       }
     },
-    "node_modules/big-integer": {
-      "version": "1.6.52",
-      "resolved": "https://registry.npmjs.org/big-integer/-/big-integer-1.6.52.tgz",
-      "integrity": "sha512-QxD8cf2eVqJOOz63z6JIN9BzvVs/dlySa5HGSBH5xtR8dPteIRQnBxxKqkNTiT6jbDTF6jAfrd4oMcND9RGbQg==",
-      "license": "Unlicense",
-      "optional": true,
-      "engines": {
-        "node": ">=0.6"
-      }
-    },
-    "node_modules/binary": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/binary/-/binary-0.3.0.tgz",
-      "integrity": "sha512-D4H1y5KYwpJgK8wk1Cue5LLPgmwHKYSChkbspQg5JtVuR5ulGckxfR62H3AE9UDkdMC8yyXlqYihuz3Aqg2XZg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "buffers": "~0.1.1",
-        "chainsaw": "~0.1.0"
-      },
-      "engines": {
-        "node": "*"
-      }
-    },
-    "node_modules/bl": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
-      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "buffer": "^5.5.0",
-        "inherits": "^2.0.4",
-        "readable-stream": "^3.4.0"
-      }
-    },
     "node_modules/bluebird": {
-      "version": "3.4.7",
-      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.4.7.tgz",
-      "integrity": "sha512-iD3898SR7sWVRHbiQv+sHUtHnMvC1o3nW5rAcqnq3uOn07DSAppZYUkIGslDz6gXC7HfunPe7YVBgoEJASPcHA==",
+      "version": "3.7.2",
+      "resolved": "https://registry.npmjs.org/bluebird/-/bluebird-3.7.2.tgz",
+      "integrity": "sha512-XpNj6GDQzdfW+r2Wnn7xiSAd7TM3jzkxGXBGTtWKuSXv1xUV+azxAm8jdWZN06QTQk+2N2XB9jRDkvbmQmcRtg==",
       "license": "MIT",
       "optional": true
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz",
+      "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "balanced-match": "^1.0.0",
-        "concat-map": "0.0.1"
+        "balanced-match": "^1.0.0"
       }
     },
     "node_modules/buffer": {
-      "version": "5.7.1",
-      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
-      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/buffer/-/buffer-6.0.3.tgz",
+      "integrity": "sha512-FTiCpNxtwiZZHEZbcbTIcZjERVICn9yq/pDFkTl95/AxzD1naBctN7YO68riM/gLSDY7sdrMby8hofADYuuqOA==",
       "funding": [
         {
           "type": "github",
@@ -504,35 +528,17 @@
       "optional": true,
       "dependencies": {
         "base64-js": "^1.3.1",
-        "ieee754": "^1.1.13"
+        "ieee754": "^1.2.1"
       }
     },
     "node_modules/buffer-crc32": {
-      "version": "0.2.13",
-      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
-      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
-      "license": "MIT",
-      "engines": {
-        "node": "*"
-      }
-    },
-    "node_modules/buffer-indexof-polyfill": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/buffer-indexof-polyfill/-/buffer-indexof-polyfill-1.0.2.tgz",
-      "integrity": "sha512-I7wzHwA3t1/lwXQh+A5PbNvJxgfo5r3xulgpYDB5zckTu/Z9oUK9biouBKQUjEqzaz3HnAT6TYoovmE+GqSf7A==",
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-1.0.0.tgz",
+      "integrity": "sha512-Db1SbgBS/fg/392AblrMJk97KggmvYhr4pB5ZIMTWtaivCPMWLkmb7m21cJvpvgK+J3nsU2CmmixNBZx4vFj/w==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=0.10"
-      }
-    },
-    "node_modules/buffers": {
-      "version": "0.1.1",
-      "resolved": "https://registry.npmjs.org/buffers/-/buffers-0.1.1.tgz",
-      "integrity": "sha512-9q/rDEGSb/Qsvv2qvzIzdluL5k7AaJOTrw23z9reQthrbF7is4CtlT0DXyO1oei2DCp4uojjzQ7igaSHp1kAEQ==",
-      "optional": true,
-      "engines": {
-        "node": ">=0.2.0"
+        "node": ">=8.0.0"
       }
     },
     "node_modules/callsites": {
@@ -553,19 +559,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/chainsaw": {
-      "version": "0.1.0",
-      "resolved": "https://registry.npmjs.org/chainsaw/-/chainsaw-0.1.0.tgz",
-      "integrity": "sha512-75kWfWt6MEKNC8xYXIdRpDehRYY/tNSgwKaJq+dbbDcxORuVrrQ+SEHoWsniVn9XPYfP4gmdWIeDk/4YNp1rNQ==",
-      "license": "MIT/X11",
-      "optional": true,
-      "dependencies": {
-        "traverse": ">=0.3.0 <0.4"
-      },
-      "engines": {
-        "node": "*"
-      }
-    },
     "node_modules/chromium-bidi": {
       "version": "14.0.0",
       "resolved": "https://registry.npmjs.org/chromium-bidi/-/chromium-bidi-14.0.0.tgz",
@@ -590,6 +583,76 @@
         "wrap-ansi": "^6.2.0"
       }
     },
+    "node_modules/cliui/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/cliui/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/wrap-ansi": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
+      "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -609,28 +672,22 @@
       "license": "MIT"
     },
     "node_modules/compress-commons": {
-      "version": "4.1.2",
-      "resolved": "https://registry.npmjs.org/compress-commons/-/compress-commons-4.1.2.tgz",
-      "integrity": "sha512-D3uMHtGc/fcO1Gt1/L7i1e33VOvD4A9hfQLP+6ewd+BvG/gQ84Yh4oftEhAdjSMgBgwGL+jsppT7JYNpo6MHHg==",
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/compress-commons/-/compress-commons-6.0.2.tgz",
+      "integrity": "sha512-6FqVXeETqWPoGcfzrXb37E50NP0LXT8kAMu5ooZayhWWdgEY4lBEEcbQNXtkuKQsGduxiIcI4gOTsxTmuq/bSg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "buffer-crc32": "^0.2.13",
-        "crc32-stream": "^4.0.2",
+        "crc-32": "^1.2.0",
+        "crc32-stream": "^6.0.0",
+        "is-stream": "^2.0.1",
         "normalize-path": "^3.0.0",
-        "readable-stream": "^3.6.0"
+        "readable-stream": "^4.0.0"
       },
       "engines": {
-        "node": ">= 10"
+        "node": ">= 14"
       }
     },
-    "node_modules/concat-map": {
-      "version": "0.0.1",
-      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
-      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/core-util-is": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
@@ -678,30 +735,61 @@
       }
     },
     "node_modules/crc32-stream": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/crc32-stream/-/crc32-stream-4.0.3.tgz",
-      "integrity": "sha512-NT7w2JVU7DFroFdYkeq8cywxrgjPHWkdX1wjpRQXPX5Asews3tA+Ght6lddQO5Mkumffp3X7GEqku3epj2toIw==",
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/crc32-stream/-/crc32-stream-6.0.0.tgz",
+      "integrity": "sha512-piICUB6ei4IlTv1+653yq5+KoqfBYmj9bw6LqXoOneTMDXk5nM1qt12mFW1caG3LlJXEKW1Bp0WggEmIfQB34g==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
         "crc-32": "^1.2.0",
-        "readable-stream": "^3.4.0"
+        "readable-stream": "^4.0.0"
       },
       "engines": {
-        "node": ">= 10"
+        "node": ">= 14"
       }
     },
-    "node_modules/data-uri-to-buffer": {
-      "version": "6.0.2",
-      "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-6.0.2.tgz",
-      "integrity": "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==",
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
       "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
       "engines": {
-        "node": ">= 14"
+        "node": ">= 8"
       }
     },
-    "node_modules/debug": {
-      "version": "4.4.3",
+    "node_modules/cross-spawn/node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "optional": true,
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/data-uri-to-buffer": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-6.0.2.tgz",
+      "integrity": "sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
       "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
       "license": "MIT",
@@ -795,11 +883,19 @@
         "safe-buffer": "~5.1.0"
       }
     },
+    "node_modules/eastasianwidth": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
+      "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/emoji-regex": {
-      "version": "8.0.0",
-      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
-      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
-      "license": "MIT"
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+      "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+      "license": "MIT",
+      "optional": true
     },
     "node_modules/end-of-stream": {
       "version": "1.4.5",
@@ -889,6 +985,26 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/event-target-shim": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/event-target-shim/-/event-target-shim-5.0.1.tgz",
+      "integrity": "sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/events": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",
+      "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=0.8.x"
+      }
+    },
     "node_modules/events-universal": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz",
@@ -965,50 +1081,36 @@
       "resolved": "https://registry.npmjs.org/async/-/async-0.2.10.tgz",
       "integrity": "sha512-eAkdoKxU6/LkKDBzLpT+t6Ff5EtfSF4wx1WfJiPEEV7WNLnDaRXk0oVysiEPm262roaachGexwUv94WhSgN5TQ=="
     },
-    "node_modules/fs-constants": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
-      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/fs-extra": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-10.1.0.tgz",
-      "integrity": "sha512-oRXApq54ETRj4eMiFzGnHWGy+zo5raudjuxN0b8H7s/RU2oW0Wvsx9O0ACRN/kRq9E8Vu/ReskGB5o3ji+FzHQ==",
-      "license": "MIT",
+    "node_modules/foreground-child": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
+      "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==",
+      "license": "ISC",
       "optional": true,
       "dependencies": {
-        "graceful-fs": "^4.2.0",
-        "jsonfile": "^6.0.1",
-        "universalify": "^2.0.0"
+        "cross-spawn": "^7.0.6",
+        "signal-exit": "^4.0.1"
       },
       "engines": {
-        "node": ">=12"
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/fs.realpath": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
-      "integrity": "sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/fstream": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/fstream/-/fstream-1.0.12.tgz",
-      "integrity": "sha512-WvJ193OHa0GHPEL+AycEJgxvBEwyfRkN1vhjca23OaPVMCaLCXTd5qAu82AjTcgP1UJmytkOKb63Ypde7raDIg==",
-      "deprecated": "This package is no longer supported.",
-      "license": "ISC",
+    "node_modules/fs-extra": {
+      "version": "11.3.4",
+      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.4.tgz",
+      "integrity": "sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==",
+      "license": "MIT",
       "optional": true,
       "dependencies": {
-        "graceful-fs": "^4.1.2",
-        "inherits": "~2.0.0",
-        "mkdirp": ">=0.5 0",
-        "rimraf": "2"
+        "graceful-fs": "^4.2.0",
+        "jsonfile": "^6.0.1",
+        "universalify": "^2.0.0"
       },
       "engines": {
-        "node": ">=0.6"
+        "node": ">=14.14"
       }
     },
     "node_modules/get-caller-file": {
@@ -1050,22 +1152,22 @@
       }
     },
     "node_modules/glob": {
-      "version": "7.2.3",
-      "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz",
-      "integrity": "sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==",
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
       "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
       "license": "ISC",
       "optional": true,
       "dependencies": {
-        "fs.realpath": "^1.0.0",
-        "inflight": "^1.0.4",
-        "inherits": "2",
-        "minimatch": "^3.1.1",
-        "once": "^1.3.0",
-        "path-is-absolute": "^1.0.0"
+        "foreground-child": "^3.1.0",
+        "jackspeak": "^3.1.2",
+        "minimatch": "^9.0.4",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^1.11.1"
       },
-      "engines": {
-        "node": "*"
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
       },
       "funding": {
         "url": "https://github.com/sponsors/isaacs"
@@ -1141,18 +1243,6 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "node_modules/inflight": {
-      "version": "1.0.6",
-      "resolved": "https://registry.npmjs.org/inflight/-/inflight-1.0.6.tgz",
-      "integrity": "sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==",
-      "deprecated": "This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "once": "^1.3.0",
-        "wrappy": "1"
-      }
-    },
     "node_modules/inherits": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
@@ -1161,9 +1251,9 @@
       "optional": true
     },
     "node_modules/ip-address": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
-      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
       "license": "MIT",
       "engines": {
         "node": ">= 12"
@@ -1184,6 +1274,19 @@
         "node": ">=8"
       }
     },
+    "node_modules/is-stream": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
+      "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/isarray": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
@@ -1197,6 +1300,22 @@
       "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
       "license": "ISC"
     },
+    "node_modules/jackspeak": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+      "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+      "license": "BlueOak-1.0.0",
+      "optional": true,
+      "dependencies": {
+        "@isaacs/cliui": "^8.0.2"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      },
+      "optionalDependencies": {
+        "@pkgjs/parseargs": "^0.11.0"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -1222,9 +1341,9 @@
       "license": "MIT"
     },
     "node_modules/jsonfile": {
-      "version": "6.2.0",
-      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.0.tgz",
-      "integrity": "sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==",
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
+      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1286,13 +1405,6 @@
       "integrity": "sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==",
       "license": "MIT"
     },
-    "node_modules/listenercount": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/listenercount/-/listenercount-1.0.1.tgz",
-      "integrity": "sha512-3mk/Zag0+IJxeDrxSgaDPy4zZ3w05PRZeJNnlWhzFz5OkX49J4krc+A8X2d2M69vGMBEX0uyl8M+W+8gH+kBqQ==",
-      "license": "ISC",
-      "optional": true
-    },
     "node_modules/locate-path": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
@@ -1305,49 +1417,19 @@
         "node": ">=8"
       }
     },
-    "node_modules/lodash.defaults": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/lodash.defaults/-/lodash.defaults-4.2.0.tgz",
-      "integrity": "sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/lodash.difference": {
-      "version": "4.5.0",
-      "resolved": "https://registry.npmjs.org/lodash.difference/-/lodash.difference-4.5.0.tgz",
-      "integrity": "sha512-dS2j+W26TQ7taQBGN8Lbbq04ssV3emRw4NY58WErlTO29pIqS0HmoT5aJ9+TUQ1N3G+JOZSji4eugsWwGp9yPA==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/lodash.flatten": {
-      "version": "4.4.0",
-      "resolved": "https://registry.npmjs.org/lodash.flatten/-/lodash.flatten-4.4.0.tgz",
-      "integrity": "sha512-C5N2Z3DgnnKr0LOpv/hKCgKdb7ZZwafIrsesve6lmzvZIRZRGaZ/l6Q8+2W7NaT+ZwO3fFlSCzCzrDCFdJfZ4g==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/lodash.isplainobject": {
-      "version": "4.0.6",
-      "resolved": "https://registry.npmjs.org/lodash.isplainobject/-/lodash.isplainobject-4.0.6.tgz",
-      "integrity": "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/lodash.union": {
-      "version": "4.6.0",
-      "resolved": "https://registry.npmjs.org/lodash.union/-/lodash.union-4.6.0.tgz",
-      "integrity": "sha512-c4pB2CdGrGdjMKYLA+XiRDO7Y0PRQbm/Gzg8qMj+QH+pFVAoTp5sBpO0odL3FjoPCGjK96p6qsP+yQoiLoOBcw==",
+    "node_modules/lodash": {
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
       "license": "MIT",
       "optional": true
     },
     "node_modules/lru-cache": {
-      "version": "7.18.3",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-7.18.3.tgz",
-      "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==",
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
       "license": "ISC",
-      "engines": {
-        "node": ">=12"
-      }
+      "optional": true
     },
     "node_modules/mime": {
       "version": "3.0.0",
@@ -1362,26 +1444,29 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
-      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "license": "ISC",
       "optional": true,
       "dependencies": {
-        "brace-expansion": "^1.1.7"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
-        "node": "*"
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "node_modules/minimist": {
-      "version": "1.2.8",
-      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
-      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
-      "license": "MIT",
+    "node_modules/minipass": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+      "license": "BlueOak-1.0.0",
       "optional": true,
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
       }
     },
     "node_modules/mitt": {
@@ -1390,19 +1475,6 @@
       "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==",
       "license": "MIT"
     },
-    "node_modules/mkdirp": {
-      "version": "0.5.6",
-      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-0.5.6.tgz",
-      "integrity": "sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "minimist": "^1.2.6"
-      },
-      "bin": {
-        "mkdirp": "bin/cmd.js"
-      }
-    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1410,9 +1482,9 @@
       "license": "MIT"
     },
     "node_modules/netmask": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.0.2.tgz",
-      "integrity": "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/netmask/-/netmask-2.1.1.tgz",
+      "integrity": "sha512-eonl3sLUha+S1GzTPxychyhnUzKyeQkZ7jLjKrBagJgPla13F+uQ71HgpFefyHgqrjEbCPkDArxYsjY8/+gLKA==",
       "license": "MIT",
       "engines": {
         "node": ">= 0.4.0"
@@ -1438,11 +1510,18 @@
         }
       }
     },
+    "node_modules/node-int64": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/node-int64/-/node-int64-0.4.0.tgz",
+      "integrity": "sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw==",
+      "license": "MIT",
+      "optional": true
+    },
     "node_modules/node-webpmux": {
-      "version": "3.1.7",
-      "resolved": "https://registry.npmjs.org/node-webpmux/-/node-webpmux-3.1.7.tgz",
-      "integrity": "sha512-ySkL4lBCto86OyQ0blAGzylWSECcn5I0lM3bYEhe75T8Zxt/BFUMHa8ktUguR7zwXNdS/Hms31VfSsYKN1383g==",
-      "license": "ISC"
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/node-webpmux/-/node-webpmux-3.2.1.tgz",
+      "integrity": "sha512-MKgpq9nFgo44pIVNx/umD3nkqb2E8oqQTfmstVsfNdx9uV4cX7a4LqA+d8AZd3v5tgJXwENKUFsXNP3bRLP8nQ==",
+      "license": "LGPL-3.0-or-later"
     },
     "node_modules/normalize-path": {
       "version": "3.0.0",
@@ -1531,6 +1610,13 @@
         "node": ">= 14"
       }
     },
+    "node_modules/package-json-from-dist": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
+      "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==",
+      "license": "BlueOak-1.0.0",
+      "optional": true
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -1570,14 +1656,31 @@
         "node": ">=8"
       }
     },
-    "node_modules/path-is-absolute": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/path-is-absolute/-/path-is-absolute-1.0.1.tgz",
-      "integrity": "sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==",
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
       "license": "MIT",
       "optional": true,
       "engines": {
-        "node": ">=0.10.0"
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-scurry": {
+      "version": "1.11.1",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+      "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+      "license": "BlueOak-1.0.0",
+      "optional": true,
+      "dependencies": {
+        "lru-cache": "^10.2.0",
+        "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
       }
     },
     "node_modules/pend": {
@@ -1601,6 +1704,16 @@
         "node": ">=10.13.0"
       }
     },
+    "node_modules/process": {
+      "version": "0.11.10",
+      "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz",
+      "integrity": "sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">= 0.6.0"
+      }
+    },
     "node_modules/process-nextick-args": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
@@ -1636,6 +1749,15 @@
         "node": ">= 14"
       }
     },
+    "node_modules/proxy-agent/node_modules/lru-cache": {
+      "version": "7.18.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-7.18.3.tgz",
+      "integrity": "sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/proxy-from-env": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
@@ -1709,18 +1831,20 @@
       }
     },
     "node_modules/readable-stream": {
-      "version": "3.6.2",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
-      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
+      "version": "4.7.0",
+      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-4.7.0.tgz",
+      "integrity": "sha512-oIGGmcpTLwPga8Bn6/Z75SVaH1z5dUut2ibSyAMVhmUggWpmDn2dapB0n7f8nwaSiRtepAsfJyfXIO5DCVAODg==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "inherits": "^2.0.3",
-        "string_decoder": "^1.1.1",
-        "util-deprecate": "^1.0.1"
+        "abort-controller": "^3.0.0",
+        "buffer": "^6.0.3",
+        "events": "^3.3.0",
+        "process": "^0.11.10",
+        "string_decoder": "^1.3.0"
       },
       "engines": {
-        "node": ">= 6"
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
       }
     },
     "node_modules/readdir-glob": {
@@ -1733,16 +1857,6 @@
         "minimatch": "^5.1.0"
       }
     },
-    "node_modules/readdir-glob/node_modules/brace-expansion": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
-      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "balanced-match": "^1.0.0"
-      }
-    },
     "node_modules/readdir-glob/node_modules/minimatch": {
       "version": "5.1.9",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.9.tgz",
@@ -1780,20 +1894,6 @@
         "node": ">=4"
       }
     },
-    "node_modules/rimraf": {
-      "version": "2.7.1",
-      "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-2.7.1.tgz",
-      "integrity": "sha512-uWjbaKIK3T1OSVptzX7Nl6PvQ3qAGtKEtVRjRuazjfL3Bx5eI409VZSqgND+4UNnmzLVdPj9FqFJNPqBZFve4w==",
-      "deprecated": "Rimraf versions prior to v4 are no longer supported",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "glob": "^7.1.3"
-      },
-      "bin": {
-        "rimraf": "bin.js"
-      }
-    },
     "node_modules/safe-buffer": {
       "version": "5.2.1",
       "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
@@ -1833,12 +1933,41 @@
       "integrity": "sha512-KiKBS8AnWGEyLzofFfmvKwpdPzqiy16LvQfK3yv/fVH7Bj13/wl3JSR1J+rfgRE9q7xUJK4qvgS8raSOeLUehw==",
       "license": "ISC"
     },
-    "node_modules/setimmediate": {
-      "version": "1.0.5",
-      "resolved": "https://registry.npmjs.org/setimmediate/-/setimmediate-1.0.5.tgz",
-      "integrity": "sha512-MATJdZp8sLqDl/68LfQmbP8zKPLQNV6BIZoIgrscFDQ+RsvK/BxeDQOgyxKKoh0y/8h3BqVFnCqQ/gd+reiIXA==",
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
       "license": "MIT",
-      "optional": true
+      "optional": true,
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/signal-exit": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+      "license": "ISC",
+      "optional": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
     },
     "node_modules/smart-buffer": {
       "version": "4.2.0",
@@ -1851,12 +1980,12 @@
       }
     },
     "node_modules/socks": {
-      "version": "2.8.7",
-      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.7.tgz",
-      "integrity": "sha512-HLpt+uLy/pxB+bum/9DzAgiKS8CX1EvbWxI4zlmgGCExImLdiad2iCwXT5Z4c9c3Eq8rP2318mPW2c+QbtjK8A==",
+      "version": "2.8.8",
+      "resolved": "https://registry.npmjs.org/socks/-/socks-2.8.8.tgz",
+      "integrity": "sha512-NlGELfPrgX2f1TAAcz0WawlLn+0r3FyhhCRpFFK2CemXenPYvzMWWZINv3eDNo9ucdwme7oCHRY0Jnbs4aIkog==",
       "license": "MIT",
       "dependencies": {
-        "ip-address": "^10.0.1",
+        "ip-address": "^10.1.1",
         "smart-buffer": "^4.2.0"
       },
       "engines": {
@@ -1889,9 +2018,9 @@
       }
     },
     "node_modules/streamx": {
-      "version": "2.23.0",
-      "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.23.0.tgz",
-      "integrity": "sha512-kn+e44esVfn2Fa/O0CPFcex27fjIL6MkVae0Mm6q+E6f0hWv578YCERbv+4m02cjxvDsPKLnmxral/rR6lBMAg==",
+      "version": "2.25.0",
+      "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.25.0.tgz",
+      "integrity": "sha512-0nQuG6jf1w+wddNEEXCF4nTg3LtufWINB5eFEN+5TNZW7KWJp6x87+JFL43vaAUPyCfH1wID+mNVyW6OHtFamg==",
       "license": "MIT",
       "dependencies": {
         "events-universal": "^1.0.0",
@@ -1910,10 +2039,30 @@
       }
     },
     "node_modules/string-width": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+      "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "eastasianwidth": "^0.2.0",
+        "emoji-regex": "^9.2.2",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/string-width-cjs": {
+      "name": "string-width",
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
       "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
       "license": "MIT",
+      "optional": true,
       "dependencies": {
         "emoji-regex": "^8.0.0",
         "is-fullwidth-code-point": "^3.0.0",
@@ -1923,11 +2072,59 @@
         "node": ">=8"
       }
     },
+    "node_modules/string-width-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/string-width-cjs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/string-width-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/strip-ansi-cjs": {
+      "name": "strip-ansi",
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
       "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
       "license": "MIT",
+      "optional": true,
       "dependencies": {
         "ansi-regex": "^5.0.1"
       },
@@ -1935,6 +2132,16 @@
         "node": ">=8"
       }
     },
+    "node_modules/strip-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/tar-fs": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-3.1.2.tgz",
@@ -1949,10 +2156,10 @@
         "bare-path": "^3.0.0"
       }
     },
-    "node_modules/tar-fs/node_modules/tar-stream": {
-      "version": "3.1.8",
-      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.8.tgz",
-      "integrity": "sha512-U6QpVRyCGHva435KoNWy9PRoi2IFYCgtEhq9nmrPPpbRacPs9IH4aJ3gbrFC8dPcXvdSZ4XXfXT5Fshbp2MtlQ==",
+    "node_modules/tar-stream": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.2.0.tgz",
+      "integrity": "sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==",
       "license": "MIT",
       "dependencies": {
         "b4a": "^1.6.4",
@@ -1961,23 +2168,6 @@
         "streamx": "^2.15.0"
       }
     },
-    "node_modules/tar-stream": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
-      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "bl": "^4.0.3",
-        "end-of-stream": "^1.4.1",
-        "fs-constants": "^1.0.0",
-        "inherits": "^2.0.3",
-        "readable-stream": "^3.1.1"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/teex": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/teex/-/teex-1.0.1.tgz",
@@ -2002,16 +2192,6 @@
       "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==",
       "license": "MIT"
     },
-    "node_modules/traverse": {
-      "version": "0.3.9",
-      "resolved": "https://registry.npmjs.org/traverse/-/traverse-0.3.9.tgz",
-      "integrity": "sha512-iawgk0hLP3SxGKDfnDJf8wTz4p2qImnyihM5Hh/sGvQ3K37dPi/w8sRhdNIxYA1TwFwc5mDhIJq+O0RsvXBKdQ==",
-      "license": "MIT/X11",
-      "optional": true,
-      "engines": {
-        "node": "*"
-      }
-    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
@@ -2019,15 +2199,15 @@
       "license": "0BSD"
     },
     "node_modules/typed-query-selector": {
-      "version": "2.12.1",
-      "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.1.tgz",
-      "integrity": "sha512-uzR+FzI8qrUEIu96oaeBJmd9E7CFEiQ3goA5qCVgc4s5llSubcfGHq9yUstZx/k4s9dXHVKsE35YWoFyvEqEHA==",
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/typed-query-selector/-/typed-query-selector-2.12.2.tgz",
+      "integrity": "sha512-EOPFbyIub4ngnEdqi2yOcNeDLaX/0jcE1JoAXQDDMIthap7FoN795lc/SHfIq2d416VufXpM8z/lD+WRm2gfOQ==",
       "license": "MIT"
     },
     "node_modules/undici-types": {
-      "version": "7.18.2",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
-      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "version": "7.19.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.19.2.tgz",
+      "integrity": "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==",
       "license": "MIT",
       "optional": true
     },
@@ -2042,55 +2222,17 @@
       }
     },
     "node_modules/unzipper": {
-      "version": "0.10.14",
-      "resolved": "https://registry.npmjs.org/unzipper/-/unzipper-0.10.14.tgz",
-      "integrity": "sha512-ti4wZj+0bQTiX2KmKWuwj7lhV+2n//uXEotUmGuQqrbVZSEGFMbI68+c6JCQ8aAmUWYvtHEz2A8K6wXvueR/6g==",
+      "version": "0.12.3",
+      "resolved": "https://registry.npmjs.org/unzipper/-/unzipper-0.12.3.tgz",
+      "integrity": "sha512-PZ8hTS+AqcGxsaQntl3IRBw65QrBI6lxzqDEL7IAo/XCEqRTKGfOX56Vea5TH9SZczRVxuzk1re04z/YjuYCJA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "big-integer": "^1.6.17",
-        "binary": "~0.3.0",
-        "bluebird": "~3.4.1",
-        "buffer-indexof-polyfill": "~1.0.0",
+        "bluebird": "~3.7.2",
         "duplexer2": "~0.1.4",
-        "fstream": "^1.0.12",
+        "fs-extra": "^11.2.0",
         "graceful-fs": "^4.2.2",
-        "listenercount": "~1.0.1",
-        "readable-stream": "~2.3.6",
-        "setimmediate": "~1.0.4"
-      }
-    },
-    "node_modules/unzipper/node_modules/readable-stream": {
-      "version": "2.3.8",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
-      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "core-util-is": "~1.0.0",
-        "inherits": "~2.0.3",
-        "isarray": "~1.0.0",
-        "process-nextick-args": "~2.0.0",
-        "safe-buffer": "~5.1.1",
-        "string_decoder": "~1.1.1",
-        "util-deprecate": "~1.0.1"
-      }
-    },
-    "node_modules/unzipper/node_modules/safe-buffer": {
-      "version": "5.1.2",
-      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
-      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/unzipper/node_modules/string_decoder": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
-      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "safe-buffer": "~5.1.0"
+        "node-int64": "^0.4.0"
       }
     },
     "node_modules/util-deprecate": {
@@ -2113,25 +2255,24 @@
       "license": "BSD-2-Clause"
     },
     "node_modules/whatsapp-web.js": {
-      "version": "1.34.6",
-      "resolved": "https://registry.npmjs.org/whatsapp-web.js/-/whatsapp-web.js-1.34.6.tgz",
-      "integrity": "sha512-+zgLBqARcVfuCG7b80c7Gkt+4Yh8w+oDWx7lL2gTA6nlaykHBne7NwJ5yGe2r7O9IYraIzs6HiCzNGKfu9AUBg==",
+      "version": "1.34.7",
+      "resolved": "https://registry.npmjs.org/whatsapp-web.js/-/whatsapp-web.js-1.34.7.tgz",
+      "integrity": "sha512-CscRtB32OnozLj+cuG9Q5f7IhnNV2EU4RGRJYeYF7wwhN6acQ0efabnFpetSEh5Y8OL4YqBj7nSQbUrTZYLDGA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@pedroslopez/moduleraid": "^5.0.2",
         "fluent-ffmpeg": "2.1.3",
-        "mime": "^3.0.0",
-        "node-fetch": "^2.6.9",
-        "node-webpmux": "3.1.7",
-        "puppeteer": "^24.31.0"
+        "mime": "3.0.0",
+        "node-fetch": "2.7.0",
+        "node-webpmux": "3.2.1",
+        "puppeteer": "24.38.0"
       },
       "engines": {
         "node": ">=18.0.0"
       },
       "optionalDependencies": {
-        "archiver": "^5.3.1",
-        "fs-extra": "^10.1.0",
-        "unzipper": "^0.10.11"
+        "archiver": "7.0.1",
+        "fs-extra": "11.3.4",
+        "unzipper": "0.12.3"
       }
     },
     "node_modules/whatwg-url": {
@@ -2163,15 +2304,99 @@
       "license": "ISC"
     },
     "node_modules/wrap-ansi": {
-      "version": "6.2.0",
-      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-6.2.0.tgz",
-      "integrity": "sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==",
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
+      "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-styles": "^6.1.0",
+        "string-width": "^5.0.1",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs": {
+      "name": "wrap-ansi",
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
       "license": "MIT",
+      "optional": true,
       "dependencies": {
         "ansi-styles": "^4.0.0",
         "string-width": "^4.1.0",
         "strip-ansi": "^6.0.0"
       },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
       "engines": {
         "node": ">=8"
       }
@@ -2183,9 +2408,9 @@
       "license": "ISC"
     },
     "node_modules/ws": {
-      "version": "8.19.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
-      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
+      "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
@@ -2244,6 +2469,47 @@
         "node": ">=6"
       }
     },
+    "node_modules/yargs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "license": "MIT"
+    },
+    "node_modules/yargs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/yauzl": {
       "version": "2.10.0",
       "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
@@ -2254,41 +2520,28 @@
         "fd-slicer": "~1.1.0"
       }
     },
-    "node_modules/zip-stream": {
-      "version": "4.1.1",
-      "resolved": "https://registry.npmjs.org/zip-stream/-/zip-stream-4.1.1.tgz",
-      "integrity": "sha512-9qv4rlDiopXg4E69k+vMHjNN63YFMe9sZMrdlvKnCjlCRWeCBswPPMPUfx+ipsAWq1LXHe70RcbaHdJJpS6hyQ==",
+    "node_modules/yauzl/node_modules/buffer-crc32": {
+      "version": "0.2.13",
+      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
+      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
       "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "archiver-utils": "^3.0.4",
-        "compress-commons": "^4.1.2",
-        "readable-stream": "^3.6.0"
-      },
       "engines": {
-        "node": ">= 10"
+        "node": "*"
       }
     },
-    "node_modules/zip-stream/node_modules/archiver-utils": {
-      "version": "3.0.4",
-      "resolved": "https://registry.npmjs.org/archiver-utils/-/archiver-utils-3.0.4.tgz",
-      "integrity": "sha512-KVgf4XQVrTjhyWmx6cte4RxonPLR9onExufI1jhvw/MQ4BB6IsZD5gT8Lq+u/+pRkWna/6JoHpiQioaqFP5Rzw==",
+    "node_modules/zip-stream": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/zip-stream/-/zip-stream-6.0.1.tgz",
+      "integrity": "sha512-zK7YHHz4ZXpW89AHXUPbQVGKI7uvkd3hzusTdotCg1UxyaVtg0zFJSTfW/Dq5f7OBBVnq6cZIaC8Ti4hb6dtCA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
-        "glob": "^7.2.3",
-        "graceful-fs": "^4.2.0",
-        "lazystream": "^1.0.0",
-        "lodash.defaults": "^4.2.0",
-        "lodash.difference": "^4.5.0",
-        "lodash.flatten": "^4.4.0",
-        "lodash.isplainobject": "^4.0.6",
-        "lodash.union": "^4.6.0",
-        "normalize-path": "^3.0.0",
-        "readable-stream": "^3.6.0"
+        "archiver-utils": "^5.0.0",
+        "compress-commons": "^6.0.2",
+        "readable-stream": "^4.0.0"
       },
       "engines": {
-        "node": ">= 10"
+        "node": ">= 14"
       }
     },
     "node_modules/zod": {
diff --git a/app/external_comms/platforms/whatsapp_bridge/package.json b/craftos_integrations/integrations/whatsapp_web/package.json
similarity index 88%
rename from app/external_comms/platforms/whatsapp_bridge/package.json
rename to craftos_integrations/integrations/whatsapp_web/package.json
index 86c3c064..fc7f5b62 100644
--- a/app/external_comms/platforms/whatsapp_bridge/package.json
+++ b/craftos_integrations/integrations/whatsapp_web/package.json
@@ -5,7 +5,7 @@
   "description": "WhatsApp Web bridge for CraftBot using whatsapp-web.js",
   "main": "bridge.js",
   "dependencies": {
-    "whatsapp-web.js": "^1.26.1",
+    "whatsapp-web.js": "^1.34.7",
     "qrcode": "^1.5.4"
   },
   "engines": {
diff --git a/craftos_integrations/logger.py b/craftos_integrations/logger.py
new file mode 100644
index 00000000..21201b05
--- /dev/null
+++ b/craftos_integrations/logger.py
@@ -0,0 +1,48 @@
+"""Logger access for the integrations package.
+
+Returns a proxy that resolves to the logger configured via
+``configure(logger=...)`` at *call time*, falling back to a stdlib logger
+when none has been configured. Resolving lazily matters because most
+modules call ``get_logger(__name__)`` at import time — before the host
+has had a chance to call ``configure()`` — and we want the host's
+logger (e.g. loguru) to be used for every message regardless of import
+order.
+
+    from .logger import get_logger
+    logger = get_logger(__name__)
+"""
+from __future__ import annotations
+
+import logging
+
+
+class _LoggerProxy:
+    """Forward attribute access to the live host logger or a stdlib fallback.
+
+    Each call (``logger.info(...)``, etc.) re-checks ``ConfigStore.logger``
+    so a host that calls ``configure(logger=...)`` AFTER modules have
+    already imported their logger still sees its messages routed correctly.
+    """
+    __slots__ = ("_name", "_fallback")
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+        self._fallback: logging.Logger | None = None
+
+    def _resolve(self):
+        from .config import ConfigStore
+        if ConfigStore.logger is not None:
+            return ConfigStore.logger
+        if self._fallback is None:
+            lg = logging.getLogger(self._name)
+            if not lg.handlers:
+                logging.basicConfig(level=logging.INFO, format="%(levelname)s: %(message)s")
+            self._fallback = lg
+        return self._fallback
+
+    def __getattr__(self, attr):
+        return getattr(self._resolve(), attr)
+
+
+def get_logger(name: str) -> "_LoggerProxy":
+    return _LoggerProxy(name)
diff --git a/craftos_integrations/manager.py b/craftos_integrations/manager.py
new file mode 100644
index 00000000..7c3d3732
--- /dev/null
+++ b/craftos_integrations/manager.py
@@ -0,0 +1,205 @@
+"""ExternalCommsManager — starts platform listeners, routes messages.
+
+The manager is decoupled from any agent class. The host passes a
+callback to initialize_manager(on_message=...); incoming messages
+are normalized to a dict and handed to the callback.
+
+Payload contract (kept unchanged from the legacy implementation):
+    source, integrationType, contactId, contactName, messageBody,
+    channelId, channelName, messageId, is_self_message, raw
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from .base import PlatformMessage
+from .config import ConfigStore, MessageCallback
+from .logger import get_logger
+from .registry import autoload_integrations, get_all_clients, get_client
+
+logger = get_logger(__name__)
+
+
+class ExternalCommsManager:
+    def __init__(self, on_message: MessageCallback):
+        self._on_message = on_message
+        self._active_clients: Dict[str, Any] = {}
+        self._running = False
+
+    async def start(self) -> None:
+        if self._running:
+            return
+
+        logger.info("[INTEGRATIONS] Starting external communications manager...")
+        autoload_integrations()
+
+        started = []
+        all_clients = get_all_clients()
+        logger.info(f"[INTEGRATIONS] Registered platforms: {list(all_clients.keys())}")
+
+        for platform_id, client in all_clients.items():
+            if not client.supports_listening:
+                continue
+            if not client.has_credentials():
+                logger.info(f"[INTEGRATIONS] {platform_id} has no credentials, skipping")
+                continue
+
+            try:
+                await client.start_listening(self._handle_platform_message)
+                if client.is_listening:
+                    self._active_clients[platform_id] = client
+                    started.append(platform_id)
+                    logger.info(f"[INTEGRATIONS] Started listening on {platform_id}")
+                else:
+                    logger.warning(f"[INTEGRATIONS] {platform_id} returned but not listening")
+            except Exception as e:
+                logger.warning(f"[INTEGRATIONS] Failed to start {platform_id}: {e}")
+
+        self._running = True
+        if started:
+            logger.info(f"[INTEGRATIONS] Active channels: {started}")
+        else:
+            logger.info("[INTEGRATIONS] No external channels started")
+
+    async def start_platform(self, platform_id: str) -> bool:
+        """Start listening on a specific platform (e.g. just after it was connected)."""
+        if platform_id in self._active_clients:
+            client = self._active_clients[platform_id]
+            if client.is_listening:
+                return True
+            del self._active_clients[platform_id]
+
+        autoload_integrations()
+        client = get_client(platform_id)
+        if client is None or not client.supports_listening or not client.has_credentials():
+            return False
+
+        try:
+            await client.start_listening(self._handle_platform_message)
+            if client.is_listening:
+                self._active_clients[platform_id] = client
+                logger.info(f"[INTEGRATIONS] Started listening on {platform_id} (post-connect)")
+                return True
+        except Exception as e:
+            logger.warning(f"[INTEGRATIONS] Failed to start {platform_id}: {e}")
+        return False
+
+    async def stop_platform(self, platform_id: str) -> bool:
+        client = self._active_clients.get(platform_id)
+        if client is None:
+            return False
+        try:
+            await client.stop_listening()
+        except Exception as e:
+            logger.warning(f"[INTEGRATIONS] Error stopping {platform_id}: {e}")
+        del self._active_clients[platform_id]
+        return True
+
+    async def stop(self) -> None:
+        if not self._running:
+            return
+        logger.info("[INTEGRATIONS] Stopping external communications manager...")
+        for platform_id, client in list(self._active_clients.items()):
+            try:
+                await client.stop_listening()
+            except Exception as e:
+                logger.warning(f"[INTEGRATIONS] Error stopping {platform_id}: {e}")
+        self._active_clients.clear()
+        self._running = False
+
+    async def reload(self) -> Dict[str, Any]:
+        """Stop platforms whose creds disappeared, start ones whose appeared."""
+        result: Dict[str, Any] = {"success": True, "stopped": [], "started": [], "message": ""}
+        try:
+            autoload_integrations()
+            currently_active = set(self._active_clients.keys())
+            all_clients = get_all_clients()
+
+            should_be_active = {
+                pid for pid, c in all_clients.items()
+                if c.supports_listening and c.has_credentials()
+            }
+
+            for pid in currently_active - should_be_active:
+                try:
+                    client = self._active_clients.get(pid)
+                    if client:
+                        await client.stop_listening()
+                        del self._active_clients[pid]
+                        result["stopped"].append(pid)
+                except Exception as e:
+                    logger.warning(f"[INTEGRATIONS] Error stopping {pid}: {e}")
+
+            for pid in should_be_active - currently_active:
+                try:
+                    client = all_clients.get(pid)
+                    if client:
+                        await client.start_listening(self._handle_platform_message)
+                        if client.is_listening:
+                            self._active_clients[pid] = client
+                            result["started"].append(pid)
+                except Exception as e:
+                    logger.warning(f"[INTEGRATIONS] Error starting {pid}: {e}")
+
+            result["message"] = (
+                f"Reload complete. Stopped: {len(result['stopped'])}, "
+                f"Started: {len(result['started'])}, "
+                f"Active: {len(self._active_clients)}"
+            )
+        except Exception as e:
+            result["success"] = False
+            result["message"] = f"Reload failed: {e}"
+            logger.error(f"[INTEGRATIONS] Reload failed: {e}")
+        return result
+
+    async def _handle_platform_message(self, msg: PlatformMessage) -> None:
+        payload = {
+            "source": msg.platform.replace("_", " ").title(),
+            "integrationType": msg.platform,
+            "contactId": msg.sender_id,
+            "contactName": msg.sender_name or msg.sender_id,
+            "messageBody": msg.text,
+            "channelId": msg.channel_id,
+            "channelName": msg.channel_name,
+            "messageId": msg.message_id,
+            "is_self_message": msg.raw.get("is_self_message", False),
+            "raw": msg.raw,
+        }
+        logger.info(
+            f"[INTEGRATIONS] Received from {payload['source']}: "
+            f"{payload['contactName']}: {payload['messageBody'][:50]}..."
+        )
+        try:
+            await self._on_message(payload)
+        except Exception as e:
+            logger.error(f"[INTEGRATIONS] Error in on_message callback: {e}")
+
+    def get_status(self) -> Dict[str, Any]:
+        return {
+            "running": self._running,
+            "channels": {
+                name: {"running": client.is_listening}
+                for name, client in self._active_clients.items()
+            },
+        }
+
+
+_manager: Optional[ExternalCommsManager] = None
+
+
+def get_external_comms_manager() -> Optional[ExternalCommsManager]:
+    return _manager
+
+
+async def initialize_manager(
+    *,
+    on_message: MessageCallback,
+    auto_start: bool = True,
+) -> ExternalCommsManager:
+    """Create the manager and (by default) start listeners."""
+    global _manager
+    ConfigStore.on_message = on_message
+    _manager = ExternalCommsManager(on_message)
+    if auto_start:
+        await _manager.start()
+    return _manager
diff --git a/craftos_integrations/oauth_flow.py b/craftos_integrations/oauth_flow.py
new file mode 100644
index 00000000..6c7bd2bd
--- /dev/null
+++ b/craftos_integrations/oauth_flow.py
@@ -0,0 +1,447 @@
+"""OAuth localhost callback server + OAuthFlow composition helper.
+
+This module is fully self-contained: it provides everything an OAuth
+handler needs without reaching outside the package.
+
+Two pieces:
+
+  1. _run_localhost_callback(auth_url, *, use_https=False, ...) -> (code, error)
+     Spins up a local HTTP/HTTPS server on port 8765, opens the browser,
+     waits for the OAuth redirect, returns (code, error). Used as the
+     default oauth_runner unless the host injects one via configure().
+
+  2. OAuthFlow — class that handlers compose (not subclass). Wraps the
+     full OAuth dance: build URL, run callback server, exchange tokens,
+     optionally fetch userinfo. Returns a dict with tokens + userinfo.
+"""
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import html
+import ipaddress
+import os
+import secrets
+import ssl
+import tempfile
+import threading
+import time
+import webbrowser
+from datetime import datetime, timedelta, timezone
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from .config import ConfigStore
+from .helpers import request as http_request
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Localhost callback server (ported from agent_core.oauth_server)
+# ════════════════════════════════════════════════════════════════════════
+
+def _generate_self_signed_cert() -> Tuple[str, str]:
+    from cryptography import x509
+    from cryptography.x509.oid import NameOID
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import rsa
+
+    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    subject = issuer = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, "localhost")])
+    now = datetime.now(timezone.utc)
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(subject).issuer_name(issuer)
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now).not_valid_after(now + timedelta(days=365))
+        .add_extension(
+            x509.SubjectAlternativeName([
+                x509.DNSName("localhost"),
+                x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")),
+            ]),
+            critical=False,
+        )
+        .sign(key, hashes.SHA256())
+    )
+    cert_pem = cert.public_bytes(serialization.Encoding.PEM)
+    key_pem = key.private_bytes(
+        serialization.Encoding.PEM,
+        serialization.PrivateFormat.TraditionalOpenSSL,
+        serialization.NoEncryption(),
+    )
+    cert_fd, cert_path = tempfile.mkstemp(suffix=".pem", prefix="oauth_cert_")
+    key_fd, key_path = tempfile.mkstemp(suffix=".pem", prefix="oauth_key_")
+    try:
+        os.write(cert_fd, cert_pem); os.close(cert_fd)
+        os.write(key_fd, key_pem); os.close(key_fd)
+    except Exception:
+        os.close(cert_fd); os.close(key_fd)
+        _cleanup_files(cert_path, key_path)
+        raise
+    return cert_path, key_path
+
+
+def _cleanup_files(*paths: str) -> None:
+    for p in paths:
+        try:
+            os.unlink(p)
+        except OSError:
+            pass
+
+
+def _make_callback_handler(result_holder: Dict[str, Any]):
+    class _OAuthCallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            params = parse_qs(urlparse(self.path).query)
+            returned_state = params.get("state", [None])[0]
+            result_holder["error"] = params.get("error", [None])[0]
+
+            expected_state = result_holder.get("expected_state")
+            if expected_state and returned_state != expected_state:
+                result_holder["error"] = "OAuth state mismatch — possible CSRF attack"
+                result_holder["code"] = None
+            else:
+                result_holder["code"] = params.get("code", [None])[0]
+
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            if result_holder["code"]:
+                self.wfile.write(b"<h2>Authorization successful!</h2><p>You can close this tab.</p>")
+            else:
+                safe = html.escape(str(result_holder.get("error") or "Unknown error"))
+                self.wfile.write(f"<h2>Failed</h2><p>{safe}</p>".encode())
+
+        def log_message(self, format, *args):
+            pass
+
+    return _OAuthCallbackHandler
+
+
+def _serve_until_code(
+    server: HTTPServer,
+    deadline: float,
+    result_holder: Dict[str, Any],
+    cancel_event: Optional[threading.Event] = None,
+) -> None:
+    while time.time() < deadline:
+        if cancel_event and cancel_event.is_set():
+            break
+        remaining = max(0.1, deadline - time.time())
+        server.timeout = min(remaining, 0.5)
+        try:
+            server.handle_request()
+        except Exception:
+            pass
+        if result_holder.get("code") or result_holder.get("error"):
+            break
+
+
+def _run_oauth_flow_sync(
+    auth_url: str,
+    port: int = 8765,
+    timeout: int = 120,
+    use_https: bool = False,
+    cancel_event: Optional[threading.Event] = None,
+) -> Tuple[Optional[str], Optional[str]]:
+    if cancel_event and cancel_event.is_set():
+        return None, "OAuth cancelled"
+
+    expected_state = parse_qs(urlparse(auth_url).query).get("state", [None])[0]
+    result_holder: Dict[str, Any] = {
+        "code": None, "state": None, "error": None,
+        "expected_state": expected_state,
+    }
+    handler_class = _make_callback_handler(result_holder)
+
+    try:
+        server = HTTPServer(("127.0.0.1", port), handler_class)
+    except OSError as e:
+        return None, f"Failed to start OAuth server: {e}"
+
+    if use_https:
+        cert_path = key_path = None
+        try:
+            cert_path, key_path = _generate_self_signed_cert()
+            ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+            ctx.load_cert_chain(cert_path, key_path)
+            server.socket = ctx.wrap_socket(server.socket, server_side=True)
+        except Exception as e:
+            _cleanup_files(cert_path or "", key_path or "")
+            server.server_close()
+            return None, f"Failed to set up HTTPS for OAuth: {e}"
+        finally:
+            _cleanup_files(cert_path or "", key_path or "")
+
+    scheme = "https" if use_https else "http"
+    logger.info(f"[OAUTH] {scheme.upper()} server listening on {scheme}://127.0.0.1:{port}")
+
+    deadline = time.time() + timeout
+    thread = threading.Thread(
+        target=_serve_until_code,
+        args=(server, deadline, result_holder, cancel_event),
+        daemon=True,
+    )
+    thread.start()
+
+    if cancel_event and cancel_event.is_set():
+        server.server_close()
+        return None, "OAuth cancelled"
+
+    try:
+        webbrowser.open(auth_url)
+    except Exception:
+        server.server_close()
+        return None, f"Could not open browser. Visit manually:\n{auth_url}"
+
+    while thread.is_alive():
+        thread.join(timeout=0.5)
+        if cancel_event and cancel_event.is_set():
+            break
+
+    server.server_close()
+
+    if cancel_event and cancel_event.is_set():
+        return None, "OAuth cancelled"
+    if result_holder.get("error"):
+        return None, result_holder["error"]
+    if result_holder.get("code"):
+        return result_holder["code"], None
+    return None, "OAuth timed out."
+
+
+async def run_localhost_callback(
+    auth_url: str,
+    *,
+    port: int = 8765,
+    timeout: int = 120,
+    use_https: bool = False,
+) -> Tuple[Optional[str], Optional[str]]:
+    """Default OAuth runner. Returns (code, error)."""
+    cancel_event = threading.Event()
+    loop = asyncio.get_running_loop()
+
+    def run_flow():
+        return _run_oauth_flow_sync(
+            auth_url=auth_url, port=port, timeout=timeout,
+            use_https=use_https, cancel_event=cancel_event,
+        )
+
+    try:
+        return await loop.run_in_executor(None, run_flow)
+    except asyncio.CancelledError:
+        cancel_event.set()
+        raise
+
+
+async def get_oauth_runner(auth_url: str, *, use_https: bool = False) -> Tuple[Optional[str], Optional[str]]:
+    """Resolve and call the configured oauth_runner (or the default)."""
+    runner = ConfigStore.oauth_runner or run_localhost_callback
+    return await runner(auth_url, use_https=use_https)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# OAuthFlow — composition helper for handlers
+# ════════════════════════════════════════════════════════════════════════
+
+REDIRECT_URI = "http://localhost:8765"
+REDIRECT_URI_HTTPS = "https://localhost:8765"
+
+
+class OAuthFlow:
+    """Composition helper: handlers hold an OAuthFlow instance.
+
+    Usage in a handler:
+        oauth = OAuthFlow(
+            client_id_key="GOOGLE_CLIENT_ID",
+            client_secret_key="GOOGLE_CLIENT_SECRET",
+            auth_url="https://accounts.google.com/o/oauth2/v2/auth",
+            token_url="https://oauth2.googleapis.com/token",
+            userinfo_url="https://www.googleapis.com/oauth2/v2/userinfo",
+            scopes=GOOGLE_SCOPES,
+            use_pkce=True,
+        )
+
+        result = await self.oauth.run()
+        if result.get("error"):
+            return False, result["error"]
+        save_credential(self.spec.cred_file, MyCredential(
+            access_token=result["access_token"],
+            email=result["userinfo"]["email"],
+        ))
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id_key: str,
+        client_secret_key: Optional[str],
+        auth_url: str,
+        token_url: str,
+        userinfo_url: Optional[str] = None,
+        scopes: str = "",
+        use_pkce: bool = False,
+        use_https: bool = False,
+        token_auth_basic: bool = False,
+        token_request_json: bool = False,
+        token_extra_headers: Optional[Dict[str, str]] = None,
+        userinfo_extra_headers: Optional[Dict[str, str]] = None,
+        extra_auth_params: Optional[Dict[str, str]] = None,
+        scope_param: str = "scope",
+    ):
+        self.client_id_key = client_id_key
+        self.client_secret_key = client_secret_key
+        self.auth_url = auth_url
+        self.token_url = token_url
+        self.userinfo_url = userinfo_url
+        self.scopes = scopes
+        self.use_pkce = use_pkce
+        self.use_https = use_https
+        self.token_auth_basic = token_auth_basic
+        self.token_request_json = token_request_json
+        self.token_extra_headers = token_extra_headers or {}
+        self.userinfo_extra_headers = userinfo_extra_headers or {}
+        self.extra_auth_params = extra_auth_params or {}
+        self.scope_param = scope_param
+
+    @property
+    def redirect_uri(self) -> str:
+        return REDIRECT_URI_HTTPS if self.use_https else REDIRECT_URI
+
+    def _client_id(self) -> Optional[str]:
+        return ConfigStore.get_oauth(self.client_id_key) or None
+
+    def _client_secret(self) -> Optional[str]:
+        if not self.client_secret_key:
+            return None
+        return ConfigStore.get_oauth(self.client_secret_key) or None
+
+    def _build_auth_url(self) -> Tuple[str, Dict[str, Any]]:
+        client_id = self._client_id()
+        if not client_id:
+            raise RuntimeError(f"OAuth not configured: missing {self.client_id_key}")
+
+        state = secrets.token_urlsafe(32)
+        params: Dict[str, str] = {
+            "client_id": client_id,
+            "redirect_uri": self.redirect_uri,
+            "response_type": "code",
+            "state": state,
+        }
+        if self.scopes:
+            params[self.scope_param] = self.scopes
+
+        ctx: Dict[str, Any] = {"state": state, "client_id": client_id}
+
+        if self.use_pkce:
+            verifier = secrets.token_urlsafe(64)[:128]
+            challenge = base64.urlsafe_b64encode(
+                hashlib.sha256(verifier.encode()).digest()
+            ).decode().rstrip("=")
+            params["code_challenge"] = challenge
+            params["code_challenge_method"] = "S256"
+            ctx["code_verifier"] = verifier
+
+        params.update(self.extra_auth_params)
+        return f"{self.auth_url}?{urlencode(params)}", ctx
+
+    def _exchange_token_sync(self, code: str, ctx: Dict[str, Any]) -> Dict[str, Any]:
+        """Sync token exchange — runs in a worker thread via ``asyncio.to_thread``.
+
+        Intentionally synchronous to side-step async-context detection issues
+        that can occur after the OAuth callback executor returns control.
+        """
+        client_id = ctx["client_id"]
+        client_secret = self._client_secret()
+
+        token_data: Dict[str, str] = {
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+            "grant_type": "authorization_code",
+        }
+        if "code_verifier" in ctx:
+            token_data["code_verifier"] = ctx["code_verifier"]
+
+        headers: Dict[str, str] = dict(self.token_extra_headers)
+        if self.token_auth_basic and client_secret:
+            basic = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
+            headers["Authorization"] = f"Basic {basic}"
+        else:
+            token_data["client_id"] = client_id
+            if client_secret:
+                token_data["client_secret"] = client_secret
+
+        if self.token_request_json:
+            headers.setdefault("Content-Type", "application/json")
+            result = http_request(
+                "POST", self.token_url, json=token_data, headers=headers,
+                timeout=30.0, expected=(200,),
+            )
+        else:
+            result = http_request(
+                "POST", self.token_url, data=token_data, headers=headers,
+                timeout=30.0, expected=(200,),
+            )
+        if "error" in result:
+            return {"error": f"Token exchange failed: {result.get('details') or result['error']}"}
+        return result["result"] or {}
+
+    def _fetch_userinfo_sync(self, access_token: str) -> Dict[str, Any]:
+        """Sync userinfo fetch — runs in a worker thread."""
+        if not self.userinfo_url:
+            return {}
+        headers = {"Authorization": f"Bearer {access_token}"}
+        headers.update(self.userinfo_extra_headers)
+        result = http_request(
+            "GET", self.userinfo_url, headers=headers,
+            timeout=30.0, expected=(200,),
+        )
+        if "error" in result:
+            logger.warning(f"[OAUTH] userinfo fetch failed: {result['error']}")
+            return {}
+        return result["result"] or {}
+
+    async def run(self) -> Dict[str, Any]:
+        """Run the full OAuth flow.
+
+        Returns a dict:
+            On success: {access_token, refresh_token, expires_in, userinfo, raw, ...}
+            On failure: {error: "..."}
+        """
+        try:
+            try:
+                url, ctx = self._build_auth_url()
+            except RuntimeError as e:
+                return {"error": str(e)}
+
+            code, error = await get_oauth_runner(url, use_https=self.use_https)
+            if error:
+                return {"error": error}
+            if not code:
+                return {"error": "OAuth did not return a code"}
+
+            tokens = await asyncio.to_thread(self._exchange_token_sync, code, ctx)
+            if "error" in tokens and not tokens.get("access_token"):
+                return tokens
+
+            access_token = tokens.get("access_token", "")
+            userinfo = (
+                await asyncio.to_thread(self._fetch_userinfo_sync, access_token)
+                if access_token else {}
+            )
+
+            return {
+                "access_token": access_token,
+                "refresh_token": tokens.get("refresh_token", ""),
+                "expires_in": tokens.get("expires_in", 0),
+                "userinfo": userinfo,
+                "raw": tokens,
+            }
+        except Exception as e:
+            logger.exception(f"[OAUTH] flow crashed: {e}")
+            return {"error": f"OAuth flow error: {e}"}
diff --git a/craftos_integrations/registry.py b/craftos_integrations/registry.py
new file mode 100644
index 00000000..1eb408e5
--- /dev/null
+++ b/craftos_integrations/registry.py
@@ -0,0 +1,152 @@
+"""Registry for platform clients and integration handlers.
+
+Two parallel registries (clients and handlers) keep the runtime and auth
+lifecycles separate. Both are populated by decorators (@register_client,
+@register_handler) and resolved as singletons.
+
+autoload_integrations() walks the integrations/ subpackage and imports
+every module — that triggers the decorators. Adding a new integration
+is one file drop with no edits here.
+"""
+from __future__ import annotations
+
+import importlib
+import pkgutil
+from typing import Dict, List, Optional, Type
+
+from .base import BasePlatformClient, IntegrationHandler
+from .logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Platform clients (runtime side)
+# ════════════════════════════════════════════════════════════════════════
+
+_client_classes: Dict[str, Type[BasePlatformClient]] = {}
+_client_instances: Dict[str, BasePlatformClient] = {}
+
+
+def register_client(cls: Type[BasePlatformClient]) -> Type[BasePlatformClient]:
+    pid = cls.PLATFORM_ID
+    if not pid:
+        raise ValueError(f"{cls.__name__} has no PLATFORM_ID set")
+    _client_classes[pid] = cls
+    return cls
+
+
+def get_client(platform_id: str) -> Optional[BasePlatformClient]:
+    if platform_id in _client_instances:
+        return _client_instances[platform_id]
+    cls = _client_classes.get(platform_id)
+    if cls is None:
+        return None
+    instance = cls()
+    _client_instances[platform_id] = instance
+    return instance
+
+
+def get_all_clients() -> Dict[str, BasePlatformClient]:
+    for pid in _client_classes:
+        if pid not in _client_instances:
+            _client_instances[pid] = _client_classes[pid]()
+    return dict(_client_instances)
+
+
+def get_registered_platforms() -> List[str]:
+    return list(_client_classes.keys())
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Integration handlers (auth side)
+# ════════════════════════════════════════════════════════════════════════
+
+_handler_classes: Dict[str, Type[IntegrationHandler]] = {}
+_handler_instances: Dict[str, IntegrationHandler] = {}
+
+
+def register_handler(name: str):
+    """Decorator: @register_handler("slack")."""
+    def deco(cls: Type[IntegrationHandler]) -> Type[IntegrationHandler]:
+        _handler_classes[name] = cls
+        return cls
+    return deco
+
+
+def get_handler(name: str) -> Optional[IntegrationHandler]:
+    if name in _handler_instances:
+        return _handler_instances[name]
+    cls = _handler_classes.get(name)
+    if cls is None:
+        return None
+    instance = cls()
+    _handler_instances[name] = instance
+    return instance
+
+
+def get_all_handlers() -> Dict[str, IntegrationHandler]:
+    for name in _handler_classes:
+        if name not in _handler_instances:
+            _handler_instances[name] = _handler_classes[name]()
+    return dict(_handler_instances)
+
+
+def get_registered_handler_names() -> List[str]:
+    return list(_handler_classes.keys())
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Autoloader
+# ════════════════════════════════════════════════════════════════════════
+
+_autoloaded = False
+
+
+def autoload_integrations(force: bool = False) -> None:
+    """Import every module under craftos_integrations.integrations.
+
+    Triggers @register_client and @register_handler decorators on import.
+    Idempotent unless force=True.
+
+    The ``integrations`` subpackage is **optional**: if a host has deleted
+    the folder (or the package is being used framework-only), the autoloader
+    logs a single info line and returns. The registry stays empty and every
+    ``get_client``/``get_handler`` call returns ``None`` — callers handle
+    that gracefully via ``{"error": "Unknown integration ..."}`` envelopes.
+    """
+    global _autoloaded
+    if _autoloaded and not force:
+        return
+
+    try:
+        from . import integrations as pkg
+    except ImportError:
+        logger.info("[REGISTRY] No integrations/ subpackage found — registry stays empty.")
+        _autoloaded = True
+        return
+
+    pkg_path = getattr(pkg, "__path__", None)
+    if not pkg_path:
+        logger.info("[REGISTRY] integrations/ subpackage has no __path__ — registry stays empty.")
+        _autoloaded = True
+        return
+
+    for _, modname, _ in pkgutil.iter_modules(pkg_path):
+        if modname.startswith("_"):
+            continue
+        full = f"{pkg.__name__}.{modname}"
+        try:
+            importlib.import_module(full)
+        except Exception as e:
+            logger.warning(f"[REGISTRY] Failed to autoload {full}: {e}")
+
+    _autoloaded = True
+
+
+def reset() -> None:
+    """Clear all instances (for testing)."""
+    global _autoloaded
+    _client_instances.clear()
+    _handler_instances.clear()
+    _autoloaded = False
diff --git a/craftos_integrations/service.py b/craftos_integrations/service.py
new file mode 100644
index 00000000..fe85315e
--- /dev/null
+++ b/craftos_integrations/service.py
@@ -0,0 +1,399 @@
+"""Common-ops facade + metadata + connect dispatchers.
+
+Thin wrappers over the registry for everything that is platform-agnostic:
+- send_message, is_connected, list_connected, disconnect, status
+- Per-integration UI metadata (display_name, description, auth_type, fields)
+- connect_token / connect_oauth / connect_interactive dispatchers
+
+For platform-specific features (Discord voice, Jira transitions, LinkedIn UGC
+posts, Gmail send, etc.) callers should reach for the typed client directly:
+
+    from craftos_integrations import get_client
+    discord = get_client("discord")
+    await discord.join_voice(guild_id, channel_id)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from dataclasses import asdict, fields as dc_fields
+
+from .credentials_store import has_config, load_config, save_config
+from .registry import (
+    autoload_integrations,
+    get_all_clients,
+    get_client,
+    get_handler,
+    get_registered_handler_names,
+)
+
+
+def _resolve_handler(integration: str):
+    """Autoload + resolve handler. Returns ``(handler, None)`` on success or
+    ``(None, "Unknown integration: ...")`` if the name is unregistered."""
+    autoload_integrations()
+    handler = get_handler(integration)
+    if handler is None:
+        return None, f"Unknown integration: {integration}"
+    return handler, None
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Common ops
+# ════════════════════════════════════════════════════════════════════════
+
+async def send_message(integration: str, recipient: str, text: str, **kwargs) -> Dict[str, Any]:
+    """Send a message via any platform's BasePlatformClient.send_message."""
+    autoload_integrations()
+    client = get_client(integration)
+    if client is None:
+        return {"error": f"Unknown integration: {integration}"}
+    return await client.send_message(recipient, text, **kwargs)
+
+
+def is_connected(integration: str) -> bool:
+    """True if the integration has stored credentials."""
+    autoload_integrations()
+    client = get_client(integration)
+    if client is None:
+        return False
+    try:
+        return bool(client.has_credentials())
+    except Exception:
+        return False
+
+
+def list_connected() -> List[str]:
+    """Names of platforms that currently have credentials."""
+    autoload_integrations()
+    out: List[str] = []
+    for pid, client in get_all_clients().items():
+        try:
+            if client.has_credentials():
+                out.append(pid)
+        except Exception:
+            pass
+    return out
+
+
+def list_all() -> List[str]:
+    """Names of every registered integration handler."""
+    autoload_integrations()
+    return get_registered_handler_names()
+
+
+async def disconnect(integration: str, account_id: Optional[str] = None) -> Tuple[bool, str]:
+    """Run the integration's logout flow."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    args = [account_id] if account_id else []
+    return await handler.logout(args)
+
+
+async def status(integration: str) -> Tuple[bool, str]:
+    """Run the integration's status check."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    return await handler.status()
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Metadata
+# ════════════════════════════════════════════════════════════════════════
+
+def get_metadata(integration: str) -> Optional[Dict[str, Any]]:
+    """Static UI metadata for an integration (no I/O)."""
+    autoload_integrations()
+    handler = get_handler(integration)
+    if handler is None:
+        return None
+    config_class = getattr(handler, "config_class", None)
+    config_fields = getattr(handler, "config_fields", []) or []
+    return {
+        "id": integration,
+        "name": handler.display_name or integration,
+        "description": handler.description,
+        "auth_type": handler.auth_type,
+        "fields": [dict(f) for f in handler.fields],
+        "icon": getattr(handler, "icon", "") or "",
+        "has_config": config_class is not None,
+        "config_fields": [dict(f) for f in config_fields] if config_class else None,
+        "connect_help": getattr(handler, "connect_help", None),
+    }
+
+
+def list_metadata() -> List[Dict[str, Any]]:
+    """Static UI metadata for every registered integration."""
+    autoload_integrations()
+    return [m for name in get_registered_handler_names() if (m := get_metadata(name))]
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Per-integration runtime config (post-connect knobs)
+# ════════════════════════════════════════════════════════════════════════
+
+def _config_filename(handler) -> str:
+    """Derive the config filename from the handler's spec.
+
+    Convention: ``<cred_file_stem>_config.json``. So ``github.json`` →
+    ``github_config.json``, ``whatsapp_web.json`` → ``whatsapp_web_config.json``.
+    Keeps config and credential files visually paired in ``.credentials/``."""
+    stem = handler.spec.cred_file
+    if stem.endswith(".json"):
+        stem = stem[:-5]
+    return f"{stem}_config.json"
+
+
+def _coerce(value: Any, type_: str) -> Any:
+    """Coerce an incoming UI value to the type the dataclass expects.
+
+    The frontend sends strings/lists/booleans; the dataclass may want int
+    or list. This is the only place we apply per-type coercion."""
+    if value is None:
+        return None
+    if type_ == "number":
+        try:
+            if isinstance(value, str):
+                return int(value) if "." not in value else float(value)
+            return value
+        except (TypeError, ValueError):
+            return value
+    if type_ == "checkbox":
+        if isinstance(value, str):
+            return value.strip().lower() in ("1", "true", "yes", "on")
+        return bool(value)
+    if type_ == "list":
+        if isinstance(value, list):
+            return [str(v).strip() for v in value if str(v).strip()]
+        if isinstance(value, str):
+            return [s.strip() for s in value.split(",") if s.strip()]
+        return list(value or [])
+    # text / textarea / select → string
+    return value if isinstance(value, str) else str(value)
+
+
+def get_config_schema(integration: str) -> Optional[List[Dict[str, Any]]]:
+    """Return the handler's ``config_fields`` schema, or ``None`` if the
+    integration declares no runtime config."""
+    handler, _ = _resolve_handler(integration)
+    if handler is None:
+        return None
+    if getattr(handler, "config_class", None) is None:
+        return None
+    return [dict(f) for f in (handler.config_fields or [])]
+
+
+def get_config(integration: str) -> Optional[Dict[str, Any]]:
+    """Return the integration's current config as a plain dict.
+
+    If no config has been saved yet, returns the dataclass defaults so the
+    frontend can pre-populate the form. Returns ``None`` if the integration
+    declares no ``config_class`` at all."""
+    handler, _ = _resolve_handler(integration)
+    if handler is None:
+        return None
+    cls = getattr(handler, "config_class", None)
+    if cls is None:
+        return None
+    fname = _config_filename(handler)
+    obj = load_config(fname, cls) if has_config(fname) else cls()
+    if obj is None:
+        obj = cls()
+    return asdict(obj)
+
+
+def update_config(integration: str, values: Dict[str, Any]) -> Tuple[bool, str]:
+    """Coerce ``values`` per the handler's ``config_fields`` schema, build
+    a fresh ``config_class`` instance, persist it. Unknown keys are dropped.
+    Missing keys keep their dataclass defaults (so a partial UI update is
+    safe — the user can edit one field without resetting the others)."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    cls = getattr(handler, "config_class", None)
+    if cls is None:
+        return False, f"{integration} has no config_class declared"
+    schema = handler.config_fields or []
+    type_by_key = {f["key"]: f.get("type", "text") for f in schema}
+    valid_keys = {fld.name for fld in dc_fields(cls)}
+
+    fname = _config_filename(handler)
+    existing = load_config(fname, cls) if has_config(fname) else cls()
+    if existing is None:
+        existing = cls()
+    merged = asdict(existing)
+    for k, raw in (values or {}).items():
+        if k not in valid_keys:
+            continue
+        merged[k] = _coerce(raw, type_by_key.get(k, "text"))
+    try:
+        new_obj = cls(**merged)
+    except TypeError as e:
+        return False, f"Invalid config values: {e}"
+    save_config(fname, new_obj)
+    return True, f"{handler.display_name or integration} config saved"
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Status parsing
+# ════════════════════════════════════════════════════════════════════════
+
+def parse_status_accounts(status_message: str) -> List[Dict[str, str]]:
+    """Extract per-account info from a handler.status() message.
+
+    Status messages look like:
+        "Integration: Connected
+          - Account Name (account_id)"
+    """
+    accounts: List[Dict[str, str]] = []
+    for raw_line in status_message.split("\n"):
+        line = raw_line.strip()
+        if line.startswith("- "):
+            info = line[2:].strip()
+            if "(" in info and info.endswith(")"):
+                name_part = info[:info.rfind("(")].strip()
+                id_part = info[info.rfind("(") + 1:-1].strip()
+                accounts.append({"display": name_part, "id": id_part})
+            else:
+                accounts.append({"display": info, "id": info})
+    return accounts
+
+
+async def get_integration_info(integration: str) -> Optional[Dict[str, Any]]:
+    """Static metadata + live connection status (async; calls handler.status())."""
+    metadata = get_metadata(integration)
+    if metadata is None:
+        return None
+    handler = get_handler(integration)
+    connected = False
+    accounts: List[Dict[str, str]] = []
+    try:
+        _, status_msg = await handler.status()
+        if "Connected" in status_msg and "Not connected" not in status_msg:
+            connected = True
+            accounts = parse_status_accounts(status_msg)
+    except Exception:
+        pass
+    metadata["connected"] = connected
+    metadata["accounts"] = accounts
+    return metadata
+
+
+async def list_integrations() -> List[Dict[str, Any]]:
+    """Metadata + live connection status for every registered integration."""
+    autoload_integrations()
+    out: List[Dict[str, Any]] = []
+    for name in get_registered_handler_names():
+        info = await get_integration_info(name)
+        if info:
+            out.append(info)
+    return out
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Connect dispatchers — auto-start the matching listener on success
+# ════════════════════════════════════════════════════════════════════════
+
+async def _start_listener_for_handler(handler) -> None:
+    """If a manager is running, start the listener for this handler's platform."""
+    from .manager import get_external_comms_manager
+    manager = get_external_comms_manager()
+    if manager is None:
+        return
+    spec = getattr(handler, "spec", None)
+    platform_id = getattr(spec, "platform_id", None) if spec else None
+    if not platform_id:
+        return
+    try:
+        await manager.start_platform(platform_id)
+    except Exception:
+        pass
+
+
+async def connect_token(integration: str, credentials: Dict[str, str], *,
+                        start_listener: bool = True) -> Tuple[bool, str]:
+    """Token-based connect: dispatch to handler.connect_token() and start listener on success."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    success, message = await handler.connect_token(credentials)
+    if success and start_listener:
+        await _start_listener_for_handler(handler)
+    return success, message
+
+
+async def connect_oauth(integration: str, *, start_listener: bool = True) -> Tuple[bool, str]:
+    """OAuth-based connect: dispatch to handler.connect_oauth() and start listener on success."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    if handler.auth_type not in ("oauth", "both"):
+        return False, f"OAuth not supported for {integration}"
+    success, message = await handler.connect_oauth()
+    if success and start_listener:
+        await _start_listener_for_handler(handler)
+    return success, message
+
+
+async def connect_interactive(integration: str, *, start_listener: bool = True) -> Tuple[bool, str]:
+    """Interactive (e.g. QR) connect: dispatch to handler.connect_interactive() and start listener on success."""
+    handler, err = _resolve_handler(integration)
+    if err:
+        return False, err
+    if handler.auth_type not in ("interactive", "token_with_interactive"):
+        return False, f"Interactive login not supported for {integration}"
+    success, message = await handler.connect_interactive()
+    if success and start_listener:
+        await _start_listener_for_handler(handler)
+    return success, message
+
+
+# ════════════════════════════════════════════════════════════════════════
+# Sync wrappers — for sync callers (TUI, etc.) that can't await
+# ════════════════════════════════════════════════════════════════════════
+
+def _run_sync(coro):
+    """Run an async coroutine from sync code by spinning a fresh event loop.
+
+    WARNING: must NOT be called from inside an already-running event loop —
+    ``loop.run_until_complete`` will raise ``RuntimeError: This event loop is
+    already running``. The ``*_sync`` helpers in this module are intended for
+    purely synchronous call sites (TUI, REPL, scripts). From an async context,
+    use the async variant directly (``await list_integrations()`` etc.).
+    """
+    import asyncio as _asyncio
+    loop = _asyncio.new_event_loop()
+    try:
+        return loop.run_until_complete(coro)
+    finally:
+        loop.close()
+
+
+def list_integrations_sync() -> List[Dict[str, Any]]:
+    return _run_sync(list_integrations())
+
+
+def get_integration_info_sync(integration: str) -> Optional[Dict[str, Any]]:
+    return _run_sync(get_integration_info(integration))
+
+
+def get_integration_accounts(integration: str) -> List[Dict[str, str]]:
+    info = get_integration_info_sync(integration)
+    return info.get("accounts", []) if info else []
+
+
+def get_integration_auth_type(integration: str) -> str:
+    meta = get_metadata(integration)
+    return meta["auth_type"] if meta else "token"
+
+
+def get_integration_fields(integration: str) -> List[Dict[str, Any]]:
+    meta = get_metadata(integration)
+    return list(meta["fields"]) if meta else []
+
+
+def integration_registry() -> Dict[str, Dict[str, Any]]:
+    """Snapshot of metadata, keyed by integration id (rebuilt on each call)."""
+    return {m["id"]: m for m in list_metadata()}
diff --git a/craftos_integrations/spec.py b/craftos_integrations/spec.py
new file mode 100644
index 00000000..2003d83b
--- /dev/null
+++ b/craftos_integrations/spec.py
@@ -0,0 +1,23 @@
+"""IntegrationSpec — shared metadata held by both handler and client.
+
+Each integration declares one IntegrationSpec instance (frozen dataclass)
+and assigns it as a class attribute on its handler and client. This is
+composition: there is no shared base class for "Slack-the-thing", just
+two collaborators referencing the same metadata.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Type
+
+
+@dataclass(frozen=True)
+class IntegrationSpec:
+    name: str
+    cred_class: Type
+    cred_file: str
+    platform_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.platform_id:
+            object.__setattr__(self, "platform_id", self.name)
diff --git a/environment.yml b/environment.yml
index 76ce5557..7dd48e9c 100644
--- a/environment.yml
+++ b/environment.yml
@@ -22,7 +22,7 @@ dependencies:
   - pip:
       - croniter
       - openai==2.21.0
-      - google-generativeai==0.8.6
+      - google-genai==1.0.0
       - anthropic==0.83.0
       - chromadb==1.5.1
       - tiktoken==0.12.0
diff --git a/install.py b/install.py
index 7562d719..3c6d88dc 100644
--- a/install.py
+++ b/install.py
@@ -1756,7 +1756,7 @@ def _check_mac_python() -> None:
 
     # Print retro installation header
     _ART = [
-        " ██████╗ ██████╗  █████╗  ███████╗ ████████╗██████╗   ██████╗ ████████╗",
+        " ██████╗ ██████╗   █████╗  ███████╗ ████████╗██████╗   ██████╗ ████████╗",
         "██╔════╝ ██╔══██╗ ██╔══██╗ ██╔════╝ ╚══██╔══╝██╔══██╗ ██╔═══██╗╚══██╔══╝",
         "██║      ██████╔╝ ███████║ █████╗      ██║   ██████╔╝ ██║   ██║   ██║   ",
         "██║      ██╔══██╗ ██╔══██║ ██╔══╝      ██║   ██╔══██╗ ██║   ██║   ██║   ",
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 00000000..32af169e
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,6 @@
+[pytest]
+markers =
+    live: real end-to-end tests that hit live integrations and the real LLM (opt-in: `pytest -m live`)
+
+# By default, skip live tests so plain `pytest` stays fast and offline.
+addopts = -m "not live"
diff --git a/requirements.txt b/requirements.txt
index d9012d07..027b6196 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -13,7 +13,7 @@ chardet
 lxml
 lxml_html_clean
 openai>=1.0.0
-google-generativeai>=0.6.0
+google-genai>=1.0.0
 anthropic>=0.25.0
 chromadb
 onnxruntime
@@ -43,6 +43,7 @@ python-dotenv
 scikit-learn
 watchdog
 telethon
+lark-oapi              # Lark Long-Connection / WebSocket listener
 croniter>=2.0.0        # Cron expression parsing for scheduler
 playwright             # WhatsApp Web browser automation
 opencv-python-headless # Video analysis keyframe extraction
diff --git a/skills/compliance-cert-planner/SKILL.md b/skills/compliance-cert-planner/SKILL.md
index e69de29b..46a252dc 100644
--- a/skills/compliance-cert-planner/SKILL.md
+++ b/skills/compliance-cert-planner/SKILL.md
@@ -0,0 +1,34 @@
+---
+name: compliance-cert-planner
+description: Plan and sequence security and privacy compliance certifications (SOC 2, ISO 27001, GDPR, HIPAA, PCI DSS, CASA, etc.). Use when the user needs to scope which frameworks apply, classify each one, identify shared controls, and produce a roadmap.
+---
+
+# Compliance Certification Planner
+
+Help the user decide which compliance frameworks apply to their organization, what shared controls cover multiple frameworks, and in what order to pursue them.
+
+## When to use
+
+- "Which compliance certifications do we need?"
+- "Should we do SOC 2 or ISO 27001 first?"
+- "How do GDPR and HIPAA overlap for our product?"
+- "Build me a roadmap for our security compliance work."
+
+## Workflow
+
+1. **Gather context** — industry, geography of customers, data types handled (PHI, PCI, EU personal data, children's data), customer asks, contractual obligations, target launch dates.
+2. **Fill the applicability matrix** — use `templates/applicability-matrix.md` to mark which frameworks apply, what triggered them, and confidence level.
+3. **Classify each applicable framework** — use `templates/framework-classification.md` per framework (type, issuer, mandatory vs. voluntary, timeline, renewal cycle, external auditor needed).
+4. **Map shared controls** — use `templates/shared-controls-checklist.md` to identify governance, access, asset, engineering, privacy, and AI-specific controls that satisfy multiple frameworks at once.
+5. **Produce the roadmap** — use `templates/roadmap.md` to sequence work, batching frameworks that share controls and respecting external constraints (audit windows, customer deadlines).
+
+## Templates
+
+- `templates/applicability-matrix.md` — one-page yes/no/why grid across common frameworks
+- `templates/framework-classification.md` — per-framework deep dive
+- `templates/shared-controls-checklist.md` — cross-framework control inventory
+- `templates/roadmap.md` — sequenced implementation plan
+
+## Output expectations
+
+Default deliverable is a single Markdown brief containing: applicability matrix, one classification block per applicable framework, the shared-controls checklist marked up for current state, and the roadmap. Flag any framework where confidence is low or where external counsel / auditor input is required before committing.
diff --git a/skills/craftbot-skill-creator/SKILL.md b/skills/craftbot-skill-creator/SKILL.md
new file mode 100644
index 00000000..30ca4698
--- /dev/null
+++ b/skills/craftbot-skill-creator/SKILL.md
@@ -0,0 +1,266 @@
+---
+name: craftbot-skill-creator
+description: "Create a brand-new reusable skill from a single completed task. Read the per-task SKILL_SOURCE markdown the handler wrote, distil the workflow into a generalised SKILL.md, save it at skills/<name>/SKILL.md. Use this when CraftBot has spawned a 'Create Skill' workflow task and you need to author the new skill end-to-end without user interaction."
+user-invocable: false
+action-sets:
+  - file_operations
+  - core
+---
+
+# CraftBot Skill Creator
+
+Author a reusable skill from one completed task. The handler that spawned this task already gathered everything you need into a single markdown file — read it, generalise it, write the new skill, send the user a one-message summary, end the task. The handler has already posted "Creating skill `<name>`…" in chat for you, so do not duplicate that message. Your only chat message is the final presentation right before `task_end`. Do not iterate with test cases. Do not run subagents.
+
+## What you receive
+
+Your task instruction contains five lines (the two paths are **absolute** — pass them verbatim to `read_file` / `write_file`, do NOT prepend or modify any prefix):
+
+```
+Source file (read this — absolute path, use verbatim): <absolute path to SKILL_SOURCE_<id>.md>
+Target file (write the new SKILL.md here — absolute path, use verbatim): <absolute path to skills/<name>/SKILL.md>
+Mode: create
+Skill name: <kebab-case-name>
+```
+
+> ⚠️ Do not invent your own path for the target file. The handler has already placed it at the correct location under the project's `skills/` directory; using the literal value of `Target file:` puts the SKILL.md where the framework will discover it. A common mistake is generalising the source's `agent_file_system/` prefix onto the target — that lands the new skill in the wrong directory and CraftBot will never see it.
+
+`SKILL_SOURCE_<task_id>.md` has YAML frontmatter (`mode`, `target_skill`, `source_task_id`, `generated_at`) and these body sections, in order:
+
+- `## Task name` — the short task title shown in the action panel. Treat this as a one-line summary of what the user wanted, not a verbatim instruction (the original instruction is not retained on disk after the source task ends).
+- `## Outcome` — status, created/ended timestamps, the skills the source task had attached, and any internal `workflow_id`.
+- `## Action trace` — every action and reasoning item the source agent emitted, in order, with `input`, `output`, `error`, and duration. **This is your primary evidence** — it is the durable record of what actually happened, kept in `actions.db`.
+
+`create` mode means there is no existing SKILL.md for the target name; you write a fresh one.
+
+The Task name and the action trace together are enough to reconstruct the workflow. Treat the trace as the ground truth — the name is just a hint about user intent.
+
+## What you produce
+
+Two artefacts, in order:
+
+1. **One file** at the path given by `Target file:` in your task instruction (an absolute path under the project's `skills/` directory). Pass that path verbatim to `write_file` (or `create_file`). The directory does not exist yet; `write_file` creates the parent directory in the same call.
+2. **One presentation message** to the user via `send_message`, immediately after the file is written and immediately before `task_end`. See *Presentation message* below for the format.
+
+Do not write any other files. Do not send any chat message other than the single presentation one — the handler has already posted the "Creating skill …" acknowledgement.
+
+## Capture intent — from the source task
+
+You will not interview the user. The source task IS the workflow you are codifying. Read `SKILL_SOURCE_<task_id>.md` once with `read_file`, then answer these four questions for yourself before drafting:
+
+1. **What should this skill enable Claude to do?** Use the `## Task name` as a hint, then walk the `## Action trace` to see what the agent actually accomplished. Generalise: strip the specific subject ("PRs in repo X" → "summarise PRs in a repository"). The skill must be reusable across many invocations.
+2. **When should this skill trigger?** What user phrases or contexts would lead someone to want this workflow next time? Be concrete in the description (see *Description* below).
+3. **What is the output format?** Look at the final write/output actions in the trace. The skill should specify the same shape so future invocations produce comparable results.
+4. **What is the shortest happy path?** The source agent may have re-queried, backtracked, or self-corrected. Walk the trace and identify the *one* sequence that gets to the outcome. Earlier dead-ends do not belong in the skill body — but a `## Common pitfalls` section can mention them so future runs avoid them too.
+
+If the source task has very thin evidence (one or two actions, no real workflow), still write a useful skill — but keep the body short and honest. Don't pad.
+
+## Anatomy of a CraftBot skill
+
+```
+skills/<skill-name>/
+├── SKILL.md           (required)
+│   ├── YAML frontmatter
+│   └── Markdown body
+├── scripts/           (optional — executable helpers)
+├── references/        (optional — long docs the agent can read on demand)
+└── assets/            (optional — templates, fixtures)
+```
+
+You will only write `SKILL.md` in this workflow. The optional directories exist for skills authored by hand; do not create them here even if the source task touched many helper scripts. (If you notice strong repeated work in the trace, mention it in `## Common pitfalls` so a human author can come back and bundle it later.)
+
+## Frontmatter — the four fields
+
+CraftBot extends Anthropic's standard frontmatter (`name`, `description`) with two local fields (`user-invocable`, `action-sets`) — both required.
+
+```yaml
+---
+name: <kebab-case-skill-name>
+description: <one paragraph — see Description below>
+user-invocable: true
+action-sets:
+  - <action-set-1>
+  - <action-set-2>
+---
+```
+
+| Field | What it means | How to fill it |
+|---|---|---|
+| `name` | Stable kebab-case identifier. Must match the directory name. | Use the value from your task instruction verbatim. |
+| `description` | The primary triggering signal — what the skill does AND when to use it. | See *Description* below. |
+| `user-invocable` | Whether a user can pick this skill from the skill picker. | `true` for almost every new skill. Set `false` only if the skill is a silent backend workflow (memory processing, etc.) — that is not the case here. |
+| `action-sets` | Action-set names the skill actually uses. | Match the source task's `Action sets` line in SKILL_SOURCE. Drop any that the action trace shows were never actually called. The `core` set is auto-included by the framework — do not list it. |
+
+### Description — make it pushy
+
+Claude tends to *under-trigger* skills it isn't sure about. A bare functional description like "Summarise GitHub PRs" loses to a skill with the same purpose but a more directive description. Aim for two parts: what + when. Use ~50–120 words.
+
+Bad (too thin, won't trigger):
+
+```
+description: Summarise GitHub PRs.
+```
+
+Good (does the job):
+
+```
+description: Summarise the recent GitHub pull requests in a repository, grouped by author. Use this whenever the user asks for a PR digest, weekly engineering summary, "what shipped this week", or a code-review activity report — even if they don't say "PR" explicitly. Produces a markdown summary with one section per author and a one-line entry per PR.
+```
+
+The "Use this whenever…" clause is what fixes under-triggering. Include 2–4 phrasings the user might actually type, plus the output shape.
+
+## Body — sections to include
+
+The body is markdown loaded into context whenever the skill triggers. Keep it **under ~300 lines** for a one-task-derived skill (Anthropic's general ceiling is 500). If the workflow seems to need more, that is a sign you are over-fitting to the source task.
+
+Include these sections, in this order. Skip optional ones if they have nothing useful to say.
+
+1. **`# <Title-Case Name>` + one-paragraph overview.** What the skill enables. What kind of input it expects. What it produces.
+2. **`## When to use`** *(optional but recommended)*. Bullet list of trigger scenarios. The description already covers this; this section is for nuance — domains, adjacent cases, "use this instead of X when…".
+3. **`## Definition of Done`**. Numbered list of observable conditions that mark the task complete. Future agents will use this to decide whether to call `task_end`.
+4. **`## General Steps`**. Numbered list. The shortest happy path, derived from the source action trace. One imperative sentence per step. No specific values. No code.
+5. **`## Output Format`** *(if the skill produces structured output)*. The exact template the agent should write. Use a fenced code block.
+6. **`## Examples`** *(0–2 examples)*. Realistic input → output pairs. Strip identifying details. Each example should be ~5–15 lines, not pages.
+7. **`## Common pitfalls`** *(only if the source trace contained real evidence)*. Bullet list. Each bullet: the symptom you saw, then the avoidance. See *Mistake-scanning* below.
+8. **`## Allowed Actions`**. Comma-separated list of action names the skill expects to use, drawn from the source action trace.
+
+Do **not** include sections for: testing, evaluation, packaging, description optimization. Those are the human author's job. The single SKILL.md is your only deliverable.
+
+## Writing style
+
+Apply these from Anthropic's skill-creator guidance. They matter more than any individual section.
+
+- **Imperative form.** "Read the file" — not "you should read the file" or "the file must be read".
+- **Explain the why** for non-obvious rules. A short `*Why:* …` line after a rule lets future agents handle edge cases the rule didn't anticipate. Rules without rationale rot.
+- **Avoid heavy-handed MUSTs.** ALL-CAPS imperatives are a yellow flag. If you wrote `MUST` or `NEVER`, ask whether explaining the underlying reasoning would do the job better.
+- **Theory of mind.** The agent reading this skill is competent. Tell it the goal and the constraints; trust it to fill in the gaps. Don't enumerate every micro-step.
+- **Generalise.** No specific dates, names, IDs, URLs, paths copied from the source task. Concrete numbers from the source become "the relevant <thing>" or are dropped entirely. *Why:* concrete values rot the moment the skill runs against new data.
+- **Lean.** Each sentence should pull weight. After your first draft, re-read it and delete anything you wouldn't miss.
+- **No placeholder data.** If the source task used a specific spreadsheet, describe the *role* the spreadsheet played, not its column names — those will differ next time.
+
+## Mistake-scanning — the `## Common pitfalls` section
+
+Walk the action trace once with this question: *did the source agent waste time or take a wrong direction that future agents could be warned away from?*
+
+**Surface (task-specific) signals:**
+
+- Two consecutive calls to the same action with different parameters → the agent had the wrong mental model first time. Tell the new skill what the right first parameters look like.
+- An output row whose content shows the agent went the wrong direction (e.g., wrong domain, wrong filter), prompting a corrective re-action.
+- Mid-workflow context-file reads (USER.md, MEMORY.md) → front-load these in the skill so future runs don't pause to look things up.
+- Search/query that came back with too many or wrong results, prompting a more specific re-query → tell the new skill what makes the query specific enough.
+
+**Ignore (generic) signals:**
+
+- File-not-found, path-not-resolved, permission-denied — infrastructure, not workflow knowledge.
+- OS-specific errors (path separators, line endings, encoding).
+- Network timeouts, rate limits, transient HTTP errors.
+- JSON/parse errors any task could hit.
+
+**If the trace is clean** (no errors, no re-actions, perfectly linear) → omit the `## Common pitfalls` section. Don't invent pitfalls. Speculative warnings dilute real ones.
+
+## Definition of Done (for this workflow itself)
+
+You are done when all of these are true:
+
+1. `skills/<skill-name>/SKILL.md` exists at the path your task instruction specified.
+2. The frontmatter has all four fields and parses as YAML.
+3. `name` matches `<skill-name>`. `description` follows the *pushy* pattern above. `action-sets` lists only sets the source task actually used.
+4. The body has at minimum a one-paragraph overview, `## Definition of Done`, `## General Steps`, and `## Allowed Actions`.
+5. No specific values from the source task leak into the skill (no concrete dates, names, IDs, URLs, paths, file contents).
+6. Total body length is reasonable for the workflow's complexity (~80–300 lines is the right ballpark).
+7. You have sent the presentation message via `send_message` (see below).
+8. You have called `task_end` with a one-line summary.
+
+## Presentation message — required, exactly once
+
+After writing the SKILL.md and immediately before `task_end`, call `send_message` once with a short summary the user can read at a glance. Aim for 3–6 short lines. Adapt this template — do not copy verbatim:
+
+```
+✨ Created the **<skill-name>** skill.
+What it does: <one-sentence summary of the workflow it captures>.
+When it'll trigger: <one short example phrase from the description>.
+You can invoke it on future tasks via the skill picker.
+```
+
+Rules:
+- Reference the skill by name in backticks or bold so it stands out.
+- Do NOT paste the SKILL.md body. The user can open the file.
+- Do NOT mention the source task by name or include any specific values from it (consistent with the no-leak rule).
+- Keep it brief and confirmatory — this is an "it's done" message, not a tutorial.
+- The handler has already posted "Creating skill `<name>`…" in chat, so do not duplicate that or send any other chat message during the workflow.
+
+## Allowed Actions
+
+`read_file`, `create_file` (or `write_file`), `stream_edit`, `send_message`, `task_update_todos`, `task_end`.
+
+`stream_edit` is only needed if you want to refine the file you just created — write it correctly the first time and you won't need it.
+
+## Forbidden
+
+- More than one `send_message` call. The presentation message above is the only one — anything else is noise.
+- `web_search`, `run_shell`, `run_python` — outside `file_operations` + `core`.
+- Writing or modifying any file outside `skills/<skill-name>/`.
+- Overwriting an existing skill. (The handler refuses to spawn this workflow if the directory already exists; if you somehow find one there, end the task immediately rather than overwriting.)
+
+## Example: a complete worked output
+
+Source task (paraphrased): the user asked the agent to summarise the recent GitHub PRs in some repository. The action trace shows two `web_search` calls (the first too broad), one `read_file` of a USER.md to fetch the user's preferred summary length, and one `create_file` writing the final markdown digest.
+
+A reasonable `skills/pr-weekly-summary/SKILL.md`:
+
+```markdown
+---
+name: pr-weekly-summary
+description: Summarise the recent pull requests in a GitHub repository, grouped by author. Use this whenever the user asks for a PR digest, "what shipped this week", a code-review activity report, or a weekly engineering summary — even if they don't say "PR" explicitly. Produces a markdown summary with one section per author.
+user-invocable: true
+action-sets:
+  - file_operations
+  - web_research
+---
+
+# PR Weekly Summary
+
+Produce a markdown digest of recent pull requests in a GitHub repository, grouped by author. Use the user's preferred summary length from USER.md if present.
+
+## When to use
+
+- The user asks "what shipped this week?", "PR digest", "code review summary".
+- The user names a repository and a time window and asks for a status overview.
+
+## Definition of Done
+
+1. A markdown file exists at the requested output path (or, if none requested, in the workspace root).
+2. PRs are grouped by author and ordered by merge date within each author.
+3. Each PR has a one-line entry: title, number, link.
+4. Empty author groups are omitted.
+
+## General Steps
+
+1. Read USER.md to pick up the user's preferred summary verbosity if present.
+2. Confirm the repository and date window from the user's request. Default window is the last 7 days if unspecified.
+3. Fetch merged PRs in the window with `web_search`. Always include the date filter in the first query — broad queries return too many results.
+4. Group PRs by author; within each group, order by merge date descending.
+5. Write the markdown digest with `create_file`.
+6. `task_end` with a one-line summary.
+
+## Output Format
+
+```
+# PR digest for <repository> (<window>)
+
+## <Author>
+- #<number> <title> — <merge-date> — <link>
+
+## <Author>
+- ...
+```
+
+## Common pitfalls
+
+- Searches without an explicit date window return too many results. Pin the window in the first query.
+
+## Allowed Actions
+
+`web_search`, `read_file`, `create_file`, `task_update_todos`, `task_end`.
+```
+
+Notice what is *not* in this output: the specific repository name, the specific week, the count of PRs found, the actual author names, the path of the python script the source agent wrote. All of those would have rotted by the next invocation.
diff --git a/skills/craftbot-skill-improve/SKILL.md b/skills/craftbot-skill-improve/SKILL.md
new file mode 100644
index 00000000..dc7bdedf
--- /dev/null
+++ b/skills/craftbot-skill-improve/SKILL.md
@@ -0,0 +1,225 @@
+---
+name: craftbot-skill-improve
+description: "Refine an existing CraftBot skill using evidence from one completed task that used it. Read the per-task SKILL_SOURCE markdown the handler wrote, diff it against the existing SKILL.md, apply surgical edits to skills/<target>/SKILL.md. Use this when CraftBot has spawned an 'Improve Skill' workflow task and you need to refine the skill's accuracy or token efficiency without redesigning it."
+user-invocable: false
+action-sets:
+  - file_operations
+  - core
+---
+
+# CraftBot Skill Improver
+
+Refine one existing skill using evidence from one task that used it. The handler that spawned this task already gathered everything you need into a single markdown file — read it, diff it against the live skill, apply small surgical edits, send the user a one-message summary of the changes, end the task. The handler has already posted "Improving skill `<name>`…" in chat for you, so do not duplicate that message. Your only chat message is the final presentation right before `task_end`. Do not iterate with test cases. Do not run subagents.
+
+## What you receive
+
+Your task instruction contains five lines (the two paths are **absolute** — pass them verbatim to `read_file` / `stream_edit`, do NOT prepend or modify any prefix):
+
+```
+Source file (read this — absolute path, use verbatim): <absolute path to SKILL_SOURCE_<id>.md>
+Target file (edit this — absolute path, use verbatim): <absolute path to skills/<existing-name>/SKILL.md>
+Mode: improve
+Skill name: <existing-skill-name>
+```
+
+> ⚠️ Do not invent your own path for the target file. Using the literal value of `Target file:` ensures `stream_edit` modifies the actual installed SKILL.md.
+
+`SKILL_SOURCE_<task_id>.md` has YAML frontmatter (`mode: improve`, `target_skill`, `source_task_id`, `generated_at`) and these body sections:
+
+- `## Task name` — the short task title shown in the action panel. A one-line summary of intent, not a verbatim instruction.
+- `## Outcome` — status, created/ended timestamps, the skills the source task had attached, and any internal `workflow_id`.
+- `## Action trace` — every action and reasoning item, in order, with `input`, `output`, `error`, and duration. **This is your primary evidence** — it is the durable record of what actually happened.
+- `## Existing SKILL.md` — the verbatim contents of `skills/<target>/SKILL.md` *as captured at the moment the workflow started*.
+
+The target skill exists. Your job is to edit it in place. The action trace is the evidence; the existing SKILL.md is what you are diffing against.
+
+## What you produce
+
+Two artefacts, in order:
+
+1. **Targeted edits** to exactly one file: the path given by `Target file:` in your task instruction (an absolute path under the project's `skills/` directory). Pass that path verbatim to `stream_edit`. Do not use `create_file` / `write_file` — those overwrite. Do not write any other files. Do not change the directory layout. Do not delete bundled resources in `scripts/`, `references/`, or `assets/`.
+2. **One presentation message** to the user via `send_message`, immediately after the edits and immediately before `task_end`. See *Presentation message* below for the format.
+
+Do not send any chat message other than the single presentation one — the handler has already posted the "Improving skill …" acknowledgement.
+
+## Improvement constraints — what makes this different from creation
+
+These four rules are the heart of *improve* mode. Read them before drafting.
+
+1. **Do not redesign the skill.** The existing skill encodes a tested workflow. Your job is *refinement*, not rewriting. Drastic restructuring regresses use cases that this single source task never exercised.
+   *Why:* one task is a sample size of one. The skill has likely been used many times before; you are seeing one slice.
+
+2. **Optimise for accuracy AND token efficiency.** A change is justified if and only if it does one of:
+   - **Prevents a class of mistake** the source task hit (and that the existing skill did not warn about), OR
+   - **Shortens** the skill without removing meaning (kill filler, redundant restatements, dead bullets).
+   *Why:* both quality and prompt-cost matter. Skills are loaded into context every time they trigger.
+
+3. **Prefer surgical edits over wholesale rewrites.** One `stream_edit` per change. Each edit replaces or inserts a small contiguous range. If you are about to replace half the file, stop — that is redesign, not refinement.
+   *Why:* small diffs are reviewable and reversible by humans afterwards.
+
+4. **Do not invent pitfalls.** If the source task ran cleanly, do not add speculative warnings. If the trace shows the existing pitfall warnings are wrong, fix or remove them.
+   *Why:* unfounded warnings dilute real ones; agents start ignoring the section.
+
+## How to think about improvements
+
+These come straight from Anthropic's skill-improver guidance and apply here verbatim.
+
+- **Generalise from the feedback.** The skill will be invoked many more times than just this one task. If a fix only works for the source task's specific scenario, it's overfitting. Prefer changes that handle a *class* of cases, not the literal symptoms you saw.
+- **Keep the prompt lean.** Read the action trace, not just the final outputs. If the existing skill told the agent to do something that the trace shows was wasted effort, removing that instruction is a valid improvement.
+- **Explain the why.** When you add a rule, add a `*Why:* …` line right after it. When you sharpen an existing rule, preserve any existing `*Why:*` line — those are gold.
+- **Look for repeated work.** If the action trace shows the agent independently wrote the same helper logic the existing skill could have bundled, mention it in the skill body so a human author knows to bundle it later. Do *not* attempt to create `scripts/` files yourself — that's outside this workflow's scope.
+
+## CraftBot frontmatter — what you can and cannot change
+
+CraftBot skills have four frontmatter fields:
+
+| Field | Allowed change in *improve* mode |
+|---|---|
+| `name` | **Never change.** The directory name and the agent's task instruction depend on it. |
+| `description` | Edit only if the source task evidence proves the current description is wrong (e.g., the agent triggered the skill for a use case the description should explicitly cover). Apply the *pushy* pattern: what + when, with example user phrasings. |
+| `user-invocable` | Almost never change. Flip only if you have hard evidence the current value is wrong. |
+| `action-sets` | Add a set only if the trace shows the agent actually called actions from it that the skill expects. Remove a set only if the existing skill never references its actions and the trace confirms it goes unused. |
+
+## Anatomy reminder
+
+```
+skills/<skill-name>/
+├── SKILL.md           ← edit this only
+├── scripts/           ← do not modify in this workflow
+├── references/        ← do not modify in this workflow
+└── assets/            ← do not modify in this workflow
+```
+
+Bundled resources may exist for the target skill. Leave them alone. If the source trace suggests one of them is outdated, mention it in `## Common pitfalls` so a human can revisit.
+
+## Workflow
+
+Use `task_update_todos` at the start to track these. Mark each completed before moving on.
+
+1. **Read the SOURCE.** `read_file` on the path from your task instruction. Note the action trace, errors, summary, and the verbatim existing SKILL.md.
+2. **Re-read the live target.** `read_file` on `skills/<target-skill>/SKILL.md`. The SOURCE may be milliseconds stale; the live file is authoritative for line offsets when you `stream_edit`.
+3. **Diff in your head.** Two questions:
+   - What did the source task do that the existing skill *does not document* (and should)?
+   - What did the source task do that the existing skill *says to do but evidence shows is wrong / extra*?
+4. **Plan a small edit list.** Each entry is one of: *add a pitfall*, *trim a redundant step*, *sharpen wording for accuracy*, *shrink wording for tokens*. Aim for 1–4 edits. If you find yourself listing 10, you are redesigning — pick the highest-leverage few and stop.
+5. **Apply edits.** One `stream_edit` per item in the list. Re-read the file between edits if line offsets have shifted significantly.
+6. **Send the presentation message** via `send_message`. See *Presentation message* below.
+7. **`task_end`** with a one-line summary of what changed.
+
+## Mistake-scanning — what to surface as new pitfalls
+
+Walk the action trace once. For each signal, decide whether the existing skill already warns about it. If yes, no edit needed. If no, consider adding to `## Common pitfalls`.
+
+**Surface (task-specific) signals not already covered:**
+
+- Two consecutive same-action calls with different parameters → wrong mental model first time. Add a pitfall describing the right first-pass parameters.
+- Output that shows the agent went the wrong direction → add a pitfall describing the direction to take.
+- Mid-workflow context-file reads → suggest front-loading via a step in `## General Steps` instead of a pitfall.
+- Search/query that returned too many or wrong results → add a pitfall about query specificity.
+
+**Ignore (generic) signals:**
+
+- File-not-found, path issues, permissions, OS quirks, network timeouts, rate limits, JSON parse errors. Same exclusions as in *create* mode.
+
+If `## Common pitfalls` does not exist in the target skill and you have at most one task-specific signal to add, prefer to fold it into `## General Steps` as a sharpening of an existing step rather than creating a whole new section.
+
+## Token-efficiency heuristics
+
+When trimming, prefer to delete:
+
+- Redundant restatement of the same rule in two sections.
+- Filler phrases ("It is important to note that…", "As mentioned above…", "Please ensure that you…").
+- Examples that demonstrate the same case as another example.
+- ALL-CAPS imperatives whose content is already covered by an imperative sentence elsewhere.
+
+When trimming, do **not** delete:
+
+- The frontmatter or any of its required fields.
+- The Definition of Done section (or whatever named section serves that role).
+- Real pitfalls that warn about a class of mistake.
+- `*Why:* …` reasoning lines — those are how future agents handle edge cases the rule didn't anticipate.
+
+## Definition of Done (for this workflow itself)
+
+You are done when all of these are true:
+
+1. `skills/<target-skill>/SKILL.md` has been modified, or you have decided no edit is justified and the presentation message says so.
+2. The frontmatter still parses as valid YAML and `name` is unchanged.
+3. The skill's body still covers what it did before — you didn't remove a load-bearing section.
+4. Net line-count change is within roughly ±25%. Net negative is fine and often better.
+5. No specific values from the source task have leaked into the skill (no concrete dates, names, IDs, URLs, paths, file contents).
+6. You have sent the presentation message via `send_message` (see below).
+7. You have called `task_end` with a one-line summary of what changed (e.g., "Added pitfall about over-broad search queries; trimmed redundant restatement of the date-filter rule").
+
+## Presentation message — required, exactly once
+
+After applying the edits and immediately before `task_end`, call `send_message` once with a short summary of what changed. Aim for 3–6 short lines. Adapt this template — do not copy verbatim:
+
+```
+✏️ Improved the **<skill-name>** skill.
+Changes:
+- <one-line description of edit 1>
+- <one-line description of edit 2>
+The skill is now more accurate / leaner / better at <specific behaviour>.
+```
+
+If you decided no edit was justified, send a brief "no changes — the existing skill already covers the workflow cleanly" message instead.
+
+Rules:
+- Reference the skill by name in backticks or bold.
+- Summarise edits at the *behaviour* level ("now warns about over-broad searches"), not the *line* level ("inserted line at offset 47").
+- Do NOT mention the source task by name or include any specific values from it.
+- Keep it brief and confirmatory.
+- The handler has already posted "Improving skill `<name>`…" in chat, so do not duplicate that or send any other chat message during the workflow.
+
+## Allowed Actions
+
+`read_file`, `stream_edit`, `send_message`, `task_update_todos`, `task_end`.
+
+`create_file` / `write_file` are forbidden in this workflow — see *Improvement constraints* above.
+
+## Forbidden
+
+- More than one `send_message` call. The presentation message above is the only one.
+- `create_file`, `write_file` — those overwrite. Use `stream_edit`.
+- `web_search`, `run_shell`, `run_python` — outside `file_operations` + `core`.
+- Writing or modifying any file outside `skills/<target-skill>/SKILL.md`.
+- Renaming the skill directory or the `name` frontmatter field.
+- Deleting bundled resources in `scripts/`, `references/`, or `assets/`.
+
+## Example: a worked diff
+
+Existing skill `pr-weekly-summary` (excerpt):
+
+```markdown
+## General Steps
+
+1. Confirm the repository and date window from the user's request.
+2. Fetch merged PRs.
+3. Group by author and write the digest.
+```
+
+Source task evidence: the action trace shows two `web_search` calls — the first without a date filter (returned hundreds of results), the second narrowed down. The existing skill never warned about query breadth.
+
+Reasonable edits (two `stream_edit` calls):
+
+1. Sharpen step 2 of `## General Steps` to:
+   ```
+   2. Fetch merged PRs filtered by the requested date window — broad queries return too many results.
+   ```
+2. Append to (or create) `## Common pitfalls`:
+   ```
+   - Searches without an explicit date window return too many results. Pin the window in the first query.
+   ```
+
+Edits *not* to apply:
+
+- Inserting the specific repository name from the source task.
+- Inserting the specific date range used in the source task.
+- Inserting an "expected results count" hint based on the source task's count.
+- Restructuring `## General Steps` from numbered list into prose because the source agent worked through it differently.
+- Deleting the `## Output Format` section because the source task happened not to need it.
+
+## When to make no edits at all
+
+It is fine — and sometimes correct — to apply zero edits. If the action trace is perfectly linear, has no errors or re-actions, and the existing skill already covers everything the trace exhibits, the right answer is to call `task_end` with a summary like "Reviewed evidence; no improvement justified — existing skill already covers the workflow cleanly." Adding speculative content would harm the skill.
diff --git a/skills/deploy-to-vercel/Archive.zip b/skills/deploy-to-vercel/Archive.zip
new file mode 100644
index 00000000..2945baff
Binary files /dev/null and b/skills/deploy-to-vercel/Archive.zip differ
diff --git a/skills/deploy-to-vercel/SKILL.md b/skills/deploy-to-vercel/SKILL.md
new file mode 100644
index 00000000..a0251ce8
--- /dev/null
+++ b/skills/deploy-to-vercel/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: deploy-to-vercel
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+metadata:
+  author: vercel
+  version: "3.0.0"
+---
+
+# Deploy to Vercel
+
+Deploy any project to Vercel. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+The goal is to get the user into the best long-term setup: their project linked to Vercel with git-push deploys. Every method below tries to move the user closer to that state.
+
+## Step 1: Gather Project State
+
+Run all four checks before deciding which method to use:
+
+```bash
+# 1. Check for a git remote
+git remote get-url origin 2>/dev/null
+
+# 2. Check if locally linked to a Vercel project (either file means linked)
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+
+# 3. Check if the Vercel CLI is installed and authenticated
+vercel whoami 2>/dev/null
+
+# 4. List available teams (if authenticated)
+vercel teams list --format json 2>/dev/null
+```
+
+### Team selection
+
+If the user belongs to multiple teams, present all available team slugs as a bulleted list and ask which one to deploy to. Once the user picks a team, proceed immediately to the next step — do not ask for additional confirmation.
+
+Pass the team slug via `--scope` on all subsequent CLI commands (`vercel deploy`, `vercel link`, `vercel inspect`, etc.):
+
+```bash
+vercel deploy [path] -y --no-wait --scope <team-slug>
+```
+
+If the project is already linked (`.vercel/project.json` or `.vercel/repo.json` exists), the `orgId` in those files determines the team — no need to ask again. If there is only one team (or just a personal account), skip the prompt and use it directly.
+
+**About the `.vercel/` directory:** A linked project has either:
+- `.vercel/project.json` — created by `vercel link` (single project linking). Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — created by `vercel link --repo` (repo-based linking). Contains `orgId`, `remoteName`, and a `projects` array mapping directories to Vercel project IDs.
+
+Either file means the project is linked. Check for both.
+
+**Do NOT** use `vercel project inspect`, `vercel ls`, or `vercel link` to detect state in an unlinked directory — without a `.vercel/` config, they will interactively prompt (or with `--yes`, silently link as a side-effect). Only `vercel whoami` is safe to run anywhere.
+
+## Step 2: Choose a Deploy Method
+
+### Linked (`.vercel/` exists) + has git remote → Git Push
+
+This is the ideal state. The project is linked and has git integration.
+
+1. **Ask the user before pushing.** Never push without explicit approval:
+   ```
+   This project is connected to Vercel via git. I can commit and push to
+   trigger a deployment. Want me to proceed?
+   ```
+
+2. **Commit and push:**
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+   Vercel automatically builds from the push. Non-production branches get preview deployments; the production branch (usually `main`) gets a production deployment.
+
+3. **Retrieve the preview URL.** If the CLI is authenticated:
+   ```bash
+   sleep 5
+   vercel ls --format json
+   ```
+   The JSON output has a `deployments` array. Find the latest entry — its `url` field is the preview URL.
+
+   If the CLI is not authenticated, tell the user to check the Vercel dashboard or the commit status checks on their git provider for the preview URL.
+
+---
+
+### Linked (`.vercel/` exists) + no git remote → `vercel deploy`
+
+The project is linked but there's no git repo. Deploy directly with the CLI.
+
+```bash
+vercel deploy [path] -y --no-wait
+```
+
+Use `--no-wait` so the CLI returns immediately with the deployment URL instead of blocking until the build finishes (builds can take a while). Then check on the deployment status with:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+For production deploys (only if user explicitly asks):
+```bash
+vercel deploy [path] --prod -y --no-wait
+```
+
+---
+
+### Not linked + CLI is authenticated → Link first, then deploy
+
+The CLI is working but the project isn't linked yet. This is the opportunity to get the user into the best state.
+
+1. **Ask the user which team to deploy to.** Present the team slugs from Step 1 as a bulleted list. If there's only one team (or just a personal account), skip this step.
+
+2. **Once a team is selected, proceed directly to linking.** Tell the user what will happen but do not ask for separate confirmation:
+   ```
+   Linking this project to <team name> on Vercel. This will create a Vercel
+   project to deploy to and enable automatic deployments on future git pushes.
+   ```
+
+3. **If a git remote exists**, use repo-based linking with the selected team scope:
+   ```bash
+   vercel link --repo --scope <team-slug>
+   ```
+   This reads the git remote URL and matches it to existing Vercel projects that deploy from that repo. It creates `.vercel/repo.json`. This is much more reliable than `vercel link` (without `--repo`), which tries to match by directory name and often fails when the local folder and Vercel project are named differently.
+
+   **If there is no git remote**, fall back to standard linking:
+   ```bash
+   vercel link --scope <team-slug>
+   ```
+   This prompts the user to select or create a project. It creates `.vercel/project.json`.
+
+4. **Then deploy using the best available method:**
+   - If a git remote exists → commit and push (see git push method above)
+   - If no git remote → `vercel deploy [path] -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status
+
+---
+
+### Not linked + CLI not authenticated → Install, auth, link, deploy
+
+The Vercel CLI isn't set up at all.
+
+1. **Install the CLI (if not already installed):**
+   ```bash
+   npm install -g vercel
+   ```
+
+2. **Authenticate:**
+   ```bash
+   vercel login
+   ```
+   The user completes auth in their browser. If running in a non-interactive environment where login is not possible, skip to the **no-auth fallback** below.
+
+3. **Ask which team to deploy to** — present team slugs from `vercel teams list --format json` as a bulleted list. If only one team / personal account, skip. Once selected, proceed immediately.
+
+4. **Link the project** with the selected team scope (use `--repo` if a git remote exists, plain `vercel link` otherwise):
+   ```bash
+   vercel link --repo --scope <team-slug>   # if git remote exists
+   vercel link --scope <team-slug>          # if no git remote
+   ```
+
+5. **Deploy** using the best available method (git push if remote exists, otherwise `vercel deploy -y --no-wait --scope <team-slug>`, then `vercel inspect <url>` to check status).
+
+---
+
+### No-Auth Fallback — claude.ai sandbox
+
+**When to use:** Last resort when the CLI can't be installed or authenticated in the claude.ai sandbox. This requires no authentication — it returns a **Preview URL** (live site) and a **Claim URL** (transfer to your Vercel account).
+
+```bash
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
+```
+
+**Arguments:**
+- `path` - Directory to deploy, or a `.tgz` file (defaults to current directory)
+
+**Examples:**
+```bash
+# Deploy current directory
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
+
+# Deploy specific project
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
+
+# Deploy existing tarball
+bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
+```
+
+The script auto-detects the framework from `package.json`, packages the project (excluding `node_modules`, `.git`, `.env`), uploads it, and waits for the build to complete.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+---
+
+### No-Auth Fallback — Codex sandbox
+
+**When to use:** In the Codex sandbox where the CLI may not be authenticated. Codex runs in a sandboxed environment by default — try the CLI first, and fall back to the deploy script if auth fails.
+
+1. **Check whether the Vercel CLI is installed** (no escalation needed for this check):
+   ```bash
+   command -v vercel
+   ```
+
+2. **If `vercel` is installed**, try deploying with the CLI:
+   ```bash
+   vercel deploy [path] -y --no-wait
+   ```
+
+3. **If `vercel` is not installed, or the CLI fails with "No existing credentials found"**, use the fallback script:
+   ```bash
+   skill_dir="<path-to-skill>"
+
+   # Deploy current directory
+   bash "$skill_dir/resources/deploy-codex.sh"
+
+   # Deploy specific project
+   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project
+
+   # Deploy existing tarball
+   bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
+   ```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+**Escalated network access:** Only escalate the actual deploy command if sandboxing blocks the network call (`sandbox_permissions=require_escalated`). Do **not** escalate the `command -v vercel` check.
+
+---
+
+## Agent-Specific Notes
+
+### Claude Code / terminal-based agents
+
+You have full shell access. Do NOT use the `/mnt/skills/` path. Follow the decision flow above using the CLI directly.
+
+For the no-auth fallback, run the deploy script from the skill's installed location:
+```bash
+bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
+```
+The path may vary depending on where the user installed the skill.
+
+### Sandboxed environments (claude.ai)
+
+You likely cannot run `vercel login` or `git push`. Go directly to the **no-auth fallback — claude.ai sandbox**.
+
+### Codex
+
+Codex runs in a sandbox. Check if the CLI is available first, then fall back to the deploy script. Go to the **no-auth fallback — Codex sandbox**.
+
+---
+
+## Output
+
+Always show the user the deployment URL.
+
+- **Git push:** Use `vercel ls --format json` to find the preview URL. If the CLI isn't authenticated, tell the user to check the Vercel dashboard or commit status checks.
+- **CLI deploy:** Show the URL returned by `vercel deploy --no-wait`. Use `vercel inspect <url>` to check build status and report it to the user.
+- **No-auth fallback:** Show both the preview URL and the claim URL:
+  ```
+  Deployment successful!
+
+  Preview URL: https://my-app-abc123.vercel.app
+  Claim URL:   https://vercel.com/claim-deployment?code=...
+
+  View your site at the Preview URL.
+  To transfer this deployment to your Vercel account, visit the Claim URL.
+  ```
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+---
+
+## Troubleshooting
+
+### Network Egress Error (claude.ai)
+
+If deployment fails due to network restrictions on claude.ai, tell the user:
+
+```
+Deployment failed due to network restrictions. To fix this:
+
+1. Go to https://claude.ai/settings/capabilities
+2. Add *.vercel.com to the allowed domains
+3. Try deploying again
+```
+
+### Escalated Network Access (Codex / sandboxed environments)
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets) in a sandboxed environment, rerun with escalated permissions (`sandbox_permissions=require_escalated`). Do not escalate the initial CLI availability check — only escalate the actual deploy command.
+
+Example guidance to the user:
+```
+The deploy needs escalated network access to deploy to Vercel. I can rerun
+the command with escalated permissions — want me to proceed?
+```
+
+### CLI Auth Failure
+
+If `vercel login` or `vercel deploy` fails with authentication errors, fall back to the no-auth deploy script (claude.ai or Codex variant, depending on the environment).
diff --git a/skills/deploy-to-vercel/resources/deploy-codex.sh b/skills/deploy-to-vercel/resources/deploy-codex.sh
new file mode 100644
index 00000000..af07d0fd
--- /dev/null
+++ b/skills/deploy-to-vercel/resources/deploy-codex.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script for Codex (via claimable deploy endpoint)
+# Usage: ./deploy-codex.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://codex-deploy-skills.vercel.sh/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+    local pkg_json="$1"
+
+    if [ ! -f "$pkg_json" ]; then
+        echo "null"
+        return
+    fi
+
+    local content=$(cat "$pkg_json")
+
+    # Helper to check if a package exists in dependencies or devDependencies.
+    # Use exact matching by default, with a separate prefix matcher for scoped
+    # package families like "@remix-run/".
+    has_dep_exact() {
+        echo "$content" | grep -q "\"$1\""
+    }
+
+    has_dep_prefix() {
+        echo "$content" | grep -q "\"$1"
+    }
+
+    # Order matters - check more specific frameworks first
+
+    # Blitz
+    if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+    # Next.js
+    if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+    # Gatsby
+    if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+    # Remix
+    if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+    # React Router (v7 framework mode)
+    if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+    # TanStack Start
+    if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+    # Astro
+    if has_dep_exact "astro"; then echo "astro"; return; fi
+
+    # Hydrogen (Shopify)
+    if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+    # SvelteKit
+    if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+    # Svelte (standalone)
+    if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+    # Nuxt
+    if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+    # Vue with Vitepress
+    if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+    # Vue with Vuepress
+    if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+    # Gridsome
+    if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+    # SolidStart
+    if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+    # Docusaurus
+    if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+    # RedwoodJS
+    if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+    # Hexo
+    if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+    # Eleventy
+    if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+    # Angular / Ionic Angular
+    if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+    if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+    # Ionic React
+    if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+    # Create React App
+    if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+    # Ember
+    if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+    # Dojo
+    if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+    # Polymer
+    if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+    # Preact
+    if has_dep_exact "preact"; then echo "preact"; return; fi
+
+    # Stencil
+    if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+    # UmiJS
+    if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+    # Sapper (legacy Svelte)
+    if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+    # Saber
+    if has_dep_exact "saber"; then echo "saber"; return; fi
+
+    # Sanity
+    if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+    if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+    # Storybook
+    if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+    # NestJS
+    if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+    # Elysia
+    if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+    # Hono
+    if has_dep_exact "hono"; then echo "hono"; return; fi
+
+    # Fastify
+    if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+    # h3
+    if has_dep_exact "h3"; then echo "h3"; return; fi
+
+    # Nitro
+    if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+    # Express
+    if has_dep_exact "express"; then echo "express"; return; fi
+
+    # Vite (generic - check last among JS frameworks)
+    if has_dep_exact "vite"; then echo "vite"; return; fi
+
+    # Parcel
+    if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+    # No framework detected
+    echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+    if [ "$CLEANUP_TEMP" = true ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+    # Input is already a tarball, use it directly
+    echo "Using provided tarball..." >&2
+    TARBALL="$INPUT_PATH"
+    CLEANUP_TEMP=false
+    # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+    # Input is a directory, need to tar it
+    PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+    # Detect framework from package.json
+    FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+    # Stage files into a temporary directory to avoid mutating the source tree.
+    mkdir -p "$STAGING_DIR"
+    echo "Staging project files..." >&2
+    tar -C "$PROJECT_PATH" \
+        --exclude='node_modules' \
+        --exclude='.git' \
+        --exclude='.env' \
+        --exclude='.env.*' \
+        -cf - . | tar -C "$STAGING_DIR" -xf -
+
+    # Check if this is a static HTML project (no package.json)
+    if [ ! -f "$PROJECT_PATH/package.json" ]; then
+        # Find HTML files in root
+        HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+        HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+        # If there's exactly one HTML file and it's not index.html, rename it
+        if [ "$HTML_COUNT" -eq 1 ]; then
+            HTML_FILE=$(echo "$HTML_FILES" | head -1)
+            BASENAME=$(basename "$HTML_FILE")
+            if [ "$BASENAME" != "index.html" ]; then
+                echo "Renaming $BASENAME to index.html..." >&2
+                mv "$HTML_FILE" "$STAGING_DIR/index.html"
+            fi
+        fi
+    fi
+
+    # Create tarball from the staging directory
+    echo "Creating deployment package..." >&2
+    tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+    echo "Error: Input must be a directory or a .tgz file" >&2
+    exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+    echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+    ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+    echo "Error: $ERROR_MSG" >&2
+    exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+    echo "Error: Could not extract preview URL from response" >&2
+    echo "$RESPONSE" >&2
+    exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60  # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+    if [ "$HTTP_STATUS" -eq 200 ]; then
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    elif [ "$HTTP_STATUS" -ge 500 ]; then
+        # 5xx means still building/deploying
+        echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+        sleep 5
+        ATTEMPT=$((ATTEMPT + 1))
+    elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+        # 4xx might be an error or the app itself returns 4xx - it's responding
+        echo "" >&2
+        echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+        break
+    else
+        # Any other status, assume it's ready
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+    echo "" >&2
+    echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL:   $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/deploy-to-vercel/resources/deploy.sh b/skills/deploy-to-vercel/resources/deploy.sh
new file mode 100644
index 00000000..a458da63
--- /dev/null
+++ b/skills/deploy-to-vercel/resources/deploy.sh
@@ -0,0 +1,301 @@
+#!/bin/bash
+
+# Vercel Deployment Script (via claimable deploy endpoint)
+# Usage: ./deploy.sh [project-path]
+# Returns: JSON with previewUrl, claimUrl, deploymentId, projectId
+
+set -euo pipefail
+
+DEPLOY_ENDPOINT="https://claude-skills-deploy.vercel.com/api/deploy"
+
+# Detect framework from package.json
+detect_framework() {
+    local pkg_json="$1"
+
+    if [ ! -f "$pkg_json" ]; then
+        echo "null"
+        return
+    fi
+
+    local content=$(cat "$pkg_json")
+
+    # Helper to check if a package exists in dependencies or devDependencies.
+    # Use exact matching by default, with a separate prefix matcher for scoped
+    # package families like "@remix-run/".
+    has_dep_exact() {
+        echo "$content" | grep -q "\"$1\""
+    }
+
+    has_dep_prefix() {
+        echo "$content" | grep -q "\"$1"
+    }
+
+    # Order matters - check more specific frameworks first
+
+    # Blitz
+    if has_dep_exact "blitz"; then echo "blitzjs"; return; fi
+
+    # Next.js
+    if has_dep_exact "next"; then echo "nextjs"; return; fi
+
+    # Gatsby
+    if has_dep_exact "gatsby"; then echo "gatsby"; return; fi
+
+    # Remix
+    if has_dep_prefix "@remix-run/"; then echo "remix"; return; fi
+
+    # React Router (v7 framework mode)
+    if has_dep_prefix "@react-router/"; then echo "react-router"; return; fi
+
+    # TanStack Start
+    if has_dep_exact "@tanstack/start"; then echo "tanstack-start"; return; fi
+
+    # Astro
+    if has_dep_exact "astro"; then echo "astro"; return; fi
+
+    # Hydrogen (Shopify)
+    if has_dep_exact "@shopify/hydrogen"; then echo "hydrogen"; return; fi
+
+    # SvelteKit
+    if has_dep_exact "@sveltejs/kit"; then echo "sveltekit-1"; return; fi
+
+    # Svelte (standalone)
+    if has_dep_exact "svelte"; then echo "svelte"; return; fi
+
+    # Nuxt
+    if has_dep_exact "nuxt"; then echo "nuxtjs"; return; fi
+
+    # Vue with Vitepress
+    if has_dep_exact "vitepress"; then echo "vitepress"; return; fi
+
+    # Vue with Vuepress
+    if has_dep_exact "vuepress"; then echo "vuepress"; return; fi
+
+    # Gridsome
+    if has_dep_exact "gridsome"; then echo "gridsome"; return; fi
+
+    # SolidStart
+    if has_dep_exact "@solidjs/start"; then echo "solidstart-1"; return; fi
+
+    # Docusaurus
+    if has_dep_exact "@docusaurus/core"; then echo "docusaurus-2"; return; fi
+
+    # RedwoodJS
+    if has_dep_prefix "@redwoodjs/"; then echo "redwoodjs"; return; fi
+
+    # Hexo
+    if has_dep_exact "hexo"; then echo "hexo"; return; fi
+
+    # Eleventy
+    if has_dep_exact "@11ty/eleventy"; then echo "eleventy"; return; fi
+
+    # Angular / Ionic Angular
+    if has_dep_exact "@ionic/angular"; then echo "ionic-angular"; return; fi
+    if has_dep_exact "@angular/core"; then echo "angular"; return; fi
+
+    # Ionic React
+    if has_dep_exact "@ionic/react"; then echo "ionic-react"; return; fi
+
+    # Create React App
+    if has_dep_exact "react-scripts"; then echo "create-react-app"; return; fi
+
+    # Ember
+    if has_dep_exact "ember-cli" || has_dep_exact "ember-source"; then echo "ember"; return; fi
+
+    # Dojo
+    if has_dep_exact "@dojo/framework"; then echo "dojo"; return; fi
+
+    # Polymer
+    if has_dep_prefix "@polymer/"; then echo "polymer"; return; fi
+
+    # Preact
+    if has_dep_exact "preact"; then echo "preact"; return; fi
+
+    # Stencil
+    if has_dep_exact "@stencil/core"; then echo "stencil"; return; fi
+
+    # UmiJS
+    if has_dep_exact "umi"; then echo "umijs"; return; fi
+
+    # Sapper (legacy Svelte)
+    if has_dep_exact "sapper"; then echo "sapper"; return; fi
+
+    # Saber
+    if has_dep_exact "saber"; then echo "saber"; return; fi
+
+    # Sanity
+    if has_dep_exact "sanity"; then echo "sanity-v3"; return; fi
+    if has_dep_prefix "@sanity/"; then echo "sanity"; return; fi
+
+    # Storybook
+    if has_dep_prefix "@storybook/"; then echo "storybook"; return; fi
+
+    # NestJS
+    if has_dep_exact "@nestjs/core"; then echo "nestjs"; return; fi
+
+    # Elysia
+    if has_dep_exact "elysia"; then echo "elysia"; return; fi
+
+    # Hono
+    if has_dep_exact "hono"; then echo "hono"; return; fi
+
+    # Fastify
+    if has_dep_exact "fastify"; then echo "fastify"; return; fi
+
+    # h3
+    if has_dep_exact "h3"; then echo "h3"; return; fi
+
+    # Nitro
+    if has_dep_exact "nitropack"; then echo "nitro"; return; fi
+
+    # Express
+    if has_dep_exact "express"; then echo "express"; return; fi
+
+    # Vite (generic - check last among JS frameworks)
+    if has_dep_exact "vite"; then echo "vite"; return; fi
+
+    # Parcel
+    if has_dep_exact "parcel"; then echo "parcel"; return; fi
+
+    # No framework detected
+    echo "null"
+}
+
+# Parse arguments
+INPUT_PATH="${1:-.}"
+
+# Create temp directory for packaging
+TEMP_DIR=$(mktemp -d)
+TARBALL="$TEMP_DIR/project.tgz"
+STAGING_DIR="$TEMP_DIR/staging"
+CLEANUP_TEMP=true
+
+cleanup() {
+    if [ "$CLEANUP_TEMP" = true ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+echo "Preparing deployment..." >&2
+
+# Check if input is a .tgz file or a directory
+FRAMEWORK="null"
+
+if [ -f "$INPUT_PATH" ] && [[ "$INPUT_PATH" == *.tgz ]]; then
+    # Input is already a tarball, use it directly
+    echo "Using provided tarball..." >&2
+    TARBALL="$INPUT_PATH"
+    CLEANUP_TEMP=false
+    # Can't detect framework from tarball, leave as null
+elif [ -d "$INPUT_PATH" ]; then
+    # Input is a directory, need to tar it
+    PROJECT_PATH=$(cd "$INPUT_PATH" && pwd)
+
+    # Detect framework from package.json
+    FRAMEWORK=$(detect_framework "$PROJECT_PATH/package.json")
+
+    # Stage files into a temporary directory to avoid mutating the source tree.
+    mkdir -p "$STAGING_DIR"
+    echo "Staging project files..." >&2
+    tar -C "$PROJECT_PATH" \
+        --exclude='node_modules' \
+        --exclude='.git' \
+        --exclude='.env' \
+        --exclude='.env.*' \
+        -cf - . | tar -C "$STAGING_DIR" -xf -
+
+    # Check if this is a static HTML project (no package.json)
+    if [ ! -f "$PROJECT_PATH/package.json" ]; then
+        # Find HTML files in root
+        HTML_FILES=$(find "$STAGING_DIR" -maxdepth 1 -name "*.html" -type f)
+        HTML_COUNT=$(printf '%s\n' "$HTML_FILES" | sed '/^$/d' | wc -l | tr -d '[:space:]')
+
+        # If there's exactly one HTML file and it's not index.html, rename it
+        if [ "$HTML_COUNT" -eq 1 ]; then
+            HTML_FILE=$(echo "$HTML_FILES" | head -1)
+            BASENAME=$(basename "$HTML_FILE")
+            if [ "$BASENAME" != "index.html" ]; then
+                echo "Renaming $BASENAME to index.html..." >&2
+                mv "$HTML_FILE" "$STAGING_DIR/index.html"
+            fi
+        fi
+    fi
+
+    # Create tarball from the staging directory
+    echo "Creating deployment package..." >&2
+    tar -czf "$TARBALL" -C "$STAGING_DIR" .
+else
+    echo "Error: Input must be a directory or a .tgz file" >&2
+    exit 1
+fi
+
+if [ "$FRAMEWORK" != "null" ]; then
+    echo "Detected framework: $FRAMEWORK" >&2
+fi
+
+# Deploy
+echo "Deploying..." >&2
+RESPONSE=$(curl -s -X POST "$DEPLOY_ENDPOINT" -F "file=@$TARBALL" -F "framework=$FRAMEWORK")
+
+# Check for error in response
+if echo "$RESPONSE" | grep -q '"error"'; then
+    ERROR_MSG=$(echo "$RESPONSE" | grep -o '"error":"[^"]*"' | cut -d'"' -f4)
+    echo "Error: $ERROR_MSG" >&2
+    exit 1
+fi
+
+# Extract URLs from response
+PREVIEW_URL=$(echo "$RESPONSE" | grep -o '"previewUrl":"[^"]*"' | cut -d'"' -f4)
+CLAIM_URL=$(echo "$RESPONSE" | grep -o '"claimUrl":"[^"]*"' | cut -d'"' -f4)
+
+if [ -z "$PREVIEW_URL" ]; then
+    echo "Error: Could not extract preview URL from response" >&2
+    echo "$RESPONSE" >&2
+    exit 1
+fi
+
+echo "Deployment started. Waiting for build to complete..." >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+
+# Poll the preview URL until it returns a non-5xx response (5xx = still building)
+MAX_ATTEMPTS=60  # 5 minutes max (60 * 5 seconds)
+ATTEMPT=0
+
+while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+    HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$PREVIEW_URL")
+
+    if [ "$HTTP_STATUS" -eq 200 ]; then
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    elif [ "$HTTP_STATUS" -ge 500 ]; then
+        # 5xx means still building/deploying
+        echo "Building... (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" >&2
+        sleep 5
+        ATTEMPT=$((ATTEMPT + 1))
+    elif [ "$HTTP_STATUS" -ge 400 ] && [ "$HTTP_STATUS" -lt 500 ]; then
+        # 4xx might be an error or the app itself returns 4xx - it's responding
+        echo "" >&2
+        echo "Deployment ready (returned $HTTP_STATUS)!" >&2
+        break
+    else
+        # Any other status, assume it's ready
+        echo "" >&2
+        echo "Deployment ready!" >&2
+        break
+    fi
+done
+
+if [ $ATTEMPT -eq $MAX_ATTEMPTS ]; then
+    echo "" >&2
+    echo "Warning: Timed out waiting for deployment, but it may still be building." >&2
+fi
+
+echo "" >&2
+echo "Preview URL: $PREVIEW_URL" >&2
+echo "Claim URL:   $CLAIM_URL" >&2
+echo "" >&2
+
+# Output JSON for programmatic use
+echo "$RESPONSE"
diff --git a/skills/gogcli/SKILL.md b/skills/gogcli/SKILL.md
index a8ad055f..ccf8b907 100644
--- a/skills/gogcli/SKILL.md
+++ b/skills/gogcli/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: gogcli
 description: Google Workspace CLI for Gmail, Calendar, Drive, Sheets, Docs, Slides, Contacts, Tasks, People, Groups, Keep. Use when user asks to interact with Google services.
+---
 
 # gogcli - Google Workspace CLI
 
diff --git a/skills/polymarketodds/SKILL.md b/skills/polymarketodds/SKILL.md
index 47e599a8..045d3887 100644
--- a/skills/polymarketodds/SKILL.md
+++ b/skills/polymarketodds/SKILL.md
@@ -37,7 +37,7 @@ python3 {baseDir}/scripts/polymarket.py calendar
 
 ---
 
-## After Install — Suggested Setup
+## After Install - Suggested Setup
 
 ### 1. Add to Morning Briefing
 Add Polymarket to your daily cron:
@@ -181,8 +181,8 @@ Starts with $10,000 paper cash. Track your predictions without real money.
 ## Data Storage
 
 Watchlist and portfolio stored in `~/.polymarket/`:
-- `watchlist.json` — Watched markets and alert thresholds
-- `portfolio.json` — Paper positions and trade history
+- `watchlist.json` - Watched markets and alert thresholds
+- `portfolio.json` - Paper positions and trade history
 
 ---
 
@@ -232,7 +232,7 @@ Uses the public Gamma API (no auth required for reading):
 **What this skill does:**
 - Makes HTTPS GET requests to `gamma-api.polymarket.com` (public, unauthenticated)
 - Reads market data: odds, volumes, event details, price history
-- Paper trading is **local simulation only** — stored in `~/.polymarket/` as JSON files
+- Paper trading is **local simulation only** - stored in `~/.polymarket/` as JSON files
 - No real money, no wallet, no blockchain transactions
 
 **What this skill does NOT do:**
diff --git a/skills/remotion-best-practices/SKILL.md b/skills/remotion-best-practices/SKILL.md
new file mode 100644
index 00000000..829e1fdb
--- /dev/null
+++ b/skills/remotion-best-practices/SKILL.md
@@ -0,0 +1,340 @@
+---
+name: remotion-best-practices
+description: Best practices for Remotion - Video creation in React
+metadata:
+  tags: remotion, video, react, animation, composition
+---
+
+## When to use
+
+Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
+
+## New project setup
+
+When in an empty folder or workspace with no existing Remotion project, scaffold one using:
+
+```bash
+npx create-video@latest --yes --blank --no-tailwind my-video
+```
+
+Replace `my-video` with a suitable project name.
+
+## Designing a video
+
+Animate properties using `useCurrentFrame()` and `interpolate()`. Use Easing to customize the timing of the animation.
+
+```tsx
+import { useCurrentFrame, Easing } from "remotion";
+
+export const FadeIn = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+    extrapolateLeft: "clamp",
+    easing: Easing.bezier(0.16, 1, 0.3, 1),
+  });
+
+  return <div style={{ opacity }}>Hello World!</div>;
+};
+```
+
+CSS transitions or animations are FORBIDDEN - they will not render correctly.  
+Tailwind animation class names are FORBIDDEN - they will not render correctly.
+
+Place assets in the `public/` folder at your project root.
+
+Use `staticFile()` to reference files from the `public/` folder.
+
+Add images using the `<Img>` component:
+
+```tsx
+import { Img, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Img src={staticFile("logo.png")} style={{ width: 100, height: 100 }} />;
+};
+```
+
+Add videos using the `<Video>` component from `@remotion/media`:
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} style={{ opacity: 0.5 }} />;
+};
+```
+
+Add audio using the `<Audio>` component from `@remotion/media`:
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Assets can be also referenced as remote URLs:
+
+```tsx
+import { Video } from "@remotion/media";
+
+export const MyComposition = () => {
+  return <Video src="https://remotion.media/video.mp4" />
+};
+```
+
+To delay content wrap it in `<Sequence>` and use `from`.
+To limit the duration of an element, use `durationInFrames` of `<Sequence>`.
+`<Sequence>` by default is an absolute fill. For inline content, use `layout="none"`.
+
+```tsx
+import { Sequence } from "remotion";
+
+export const Title = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+    extrapolateLeft: "clamp",
+    easing: Easing.bezier(0.16, 1, 0.3, 1),
+  });
+
+  return <div style={{ opacity }}>Title</div>;
+};
+
+export const Subtitle = () => {
+  return <div>Subtitle</div>;
+};
+
+const Main = () => {
+  const {fps} = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      <Sequence>
+        <Background />
+      </Sequence>
+      <Sequence from={1 * fps} durationInFrames={2 * fps} layout="none">
+        <Title />
+      </Sequence>
+      <Sequence from={2 * fps} durationInFrames={2 * fps} layout="none">
+        <Subtitle />
+      </Sequence>
+    </AbsoluteFill>
+  );
+}
+```
+
+The width, height, fps, and duration of a video is defined in `src/Root.tsx`:
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+    />
+  );
+};
+```
+
+Metadata can also be calculated dynamically:
+
+```tsx
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+const calculateMetadata: CalculateMetadataFunction<
+  MyCompositionProps
+> = async ({ props, abortSignal }) => {
+  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
+    signal: abortSignal,
+  }).then((res) => res.json());
+
+  return {
+    durationInFrames: Math.ceil(data.duration * 30),
+    props: {
+      ...props,
+      videoUrl: data.url,
+    },
+    width: 1080,
+    height: 1080,
+  };
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ videoId: "abc123" }}
+      calculateMetadata={calculateMetadata}
+    />
+  );
+};
+```
+
+## Starting preview
+
+Start the Remotion Studio to preview a video:
+
+```bash
+npx remotion studio
+```
+
+## Optional: one-frame render check
+
+You can render a single frame with the CLI to sanity-check layout, colors, or timing.  
+Skip it for trivial edits, pure refactors, or when you already have enough confidence from Studio or prior renders.
+
+```bash
+npx remotion still [composition-id] --scale=0.25 --frame=30
+```
+
+At 30 fps, `--frame=30` is the one-second mark (`--frame` is zero-based).
+
+## Captions
+
+When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
+
+## Using FFmpeg
+
+For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the [./rules/ffmpeg.md](./rules/ffmpeg.md) file for more information.
+
+## Silence detection
+
+When needing to detect and trim silent segments from video or audio files, load the [./rules/silence-detection.md](./rules/silence-detection.md) file.
+
+## Audio visualization
+
+When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the [./rules/audio-visualization.md](./rules/audio-visualization.md) file for more information.
+
+## Sound effects
+
+When needing to use sound effects, load the [./rules/sfx.md](./rules/sfx.md) file for more information.
+
+## 3D content
+
+See [rules/3d.md](rules/3d.md) for 3D content in Remotion using Three.js and React Three Fiber.
+
+## Advanced audio
+
+See [rules/audio.md](rules/audio.md) for advanced audio features like trimming, volume, speed, pitch.
+
+## Dynamic duration, dimensions and data
+
+See [rules/calculate-metadata.md](rules/calculate-metadata.md) for dynamically set composition duration, dimensions, and props.
+
+## Advanced compositions
+
+See [rules/compositions.md](rules/compositions.md) for how to define stills, folders, default props and for how to nest compositions.
+
+## Google Fonts
+
+Is the recommended way to load fonts in Remotion. See [rules/google-fonts.md](rules/google-fonts.md) for how to load Google Fonts.
+
+## Local fonts
+
+See [rules/local-fonts.md](rules/local-fonts.md) for how to load local fonts.
+
+## Getting audio duration
+
+See [rules/get-audio-duration.md](rules/get-audio-duration.md) for getting the duration of an audio file in seconds with Mediabunny.
+
+## Getting video dimensions
+
+See [rules/get-video-dimensions.md](rules/get-video-dimensions.md) for getting the width and height of a video file with Mediabunny.
+
+## Getting video duration
+
+See [rules/get-video-duration.md](rules/get-video-duration.md) for getting the duration of a video file in seconds with Mediabunny.
+
+## GIFs
+
+See [rules/gifs.md](rules/gifs.md) for how to display GIFs synchronized with Remotion's timeline.
+
+## Advanced Images
+
+See [rules/images.md](rules/images.md) for sizing and positioning images, dynamic image paths, and getting image dimensions.
+
+## Light leaks
+
+See [rules/light-leaks.md](rules/light-leaks.md) for light leak overlay effects using `@remotion/light-leaks`.
+
+## Lottie animations
+
+See [rules/lottie.md](rules/lottie.md) for embedding Lottie animations in Remotion.
+
+## HTML in canvas
+
+See [rules/html-in-canvas.md](rules/html-in-canvas.md) if you need to render HTML into a `<canvas>` to apply 2D or WebGL effects via `<HtmlInCanvas>`.
+
+## Measuring DOM nodes
+
+See [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) for measuring DOM element dimensions in Remotion.
+
+## Measuring text
+
+See [rules/measuring-text.md](rules/measuring-text.md) for measuring text dimensions, fitting text to containers, and checking overflow.
+
+## Advanced sequencing
+
+See [rules/sequencing.md](rules/sequencing.md) for more sequencing patterns - delay, trim, limit duration of items.
+
+## TailwindCSS
+
+See [rules/tailwind.md](rules/tailwind.md) for using TailwindCSS in Remotion.
+
+## Text animations
+
+See [rules/text-animations.md](rules/text-animations.md) for typography and text animation patterns.
+
+## Advanced timing
+
+See [rules/timing.md](rules/timing.md) for advanced timing with `interpolate` and Bézier easing, and springs.
+
+## Transitions
+
+See [rules/transitions.md](rules/transitions.md) for scene transition patterns.
+
+## Transparent videos
+
+See [rules/transparent-videos.md](rules/transparent-videos.md) for rendering out a video with transparency.
+
+## Trimming
+
+See [rules/trimming.md](rules/trimming.md) for trimming patterns - cutting the beginning or end of animations.
+
+## Advanced Videos
+
+See [rules/videos.md](rules/videos.md) for advanced knowledge about embedding videos - trimming, volume, speed, looping, pitch.
+
+## Parameterized videos
+
+See [rules/parameters.md](rules/parameters.md) for making a composition parametrizable by adding a Zod schema.
+
+## Maps
+
+For simple maps with little flyovers, consider using static map images.
+For complex maps with animated routes or flyovers, load the maps rule: [rules/maplibre.md](rules/maplibre.md)
+
+## Voiceover
+
+See [rules/voiceover.md](rules/voiceover.md) for adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS.
diff --git a/skills/remotion-best-practices/rules/3d.md b/skills/remotion-best-practices/rules/3d.md
new file mode 100644
index 00000000..c9d254f1
--- /dev/null
+++ b/skills/remotion-best-practices/rules/3d.md
@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>;
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>;
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>;
+```
diff --git a/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx b/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx
new file mode 100644
index 00000000..1313ebf5
--- /dev/null
+++ b/skills/remotion-best-practices/rules/assets/charts-bar-chart.tsx
@@ -0,0 +1,173 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+const {fontFamily} = loadFont();
+
+const COLOR_BAR = '#D4AF37';
+const COLOR_TEXT = '#ffffff';
+const COLOR_MUTED = '#888888';
+const COLOR_BG = '#0a0a0a';
+const COLOR_AXIS = '#333333';
+
+// Ideal composition size: 1280x720
+
+const Title: React.FC<{children: React.ReactNode}> = ({children}) => (
+	<div style={{textAlign: 'center', marginBottom: 40}}>
+		<div style={{color: COLOR_TEXT, fontSize: 48, fontWeight: 600}}>
+			{children}
+		</div>
+	</div>
+);
+
+const YAxis: React.FC<{steps: number[]; height: number}> = ({
+	steps,
+	height,
+}) => (
+	<div
+		style={{
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'space-between',
+			height,
+			paddingRight: 16,
+		}}
+	>
+		{steps
+			.slice()
+			.reverse()
+			.map((step) => (
+				<div
+					key={step}
+					style={{
+						color: COLOR_MUTED,
+						fontSize: 20,
+						textAlign: 'right',
+					}}
+				>
+					{step.toLocaleString()}
+				</div>
+			))}
+	</div>
+);
+
+const Bar: React.FC<{
+	height: number;
+	progress: number;
+}> = ({height, progress}) => (
+	<div
+		style={{
+			flex: 1,
+			display: 'flex',
+			flexDirection: 'column',
+			justifyContent: 'flex-end',
+		}}
+	>
+		<div
+			style={{
+				width: '100%',
+				height,
+				backgroundColor: COLOR_BAR,
+				borderRadius: '8px 8px 0 0',
+				opacity: progress,
+			}}
+		/>
+	</div>
+);
+
+const XAxis: React.FC<{
+	children: React.ReactNode;
+	labels: string[];
+	height: number;
+}> = ({children, labels, height}) => (
+	<div style={{flex: 1, display: 'flex', flexDirection: 'column'}}>
+		<div
+			style={{
+				display: 'flex',
+				alignItems: 'flex-end',
+				gap: 16,
+				height,
+				borderLeft: `2px solid ${COLOR_AXIS}`,
+				borderBottom: `2px solid ${COLOR_AXIS}`,
+				paddingLeft: 16,
+			}}
+		>
+			{children}
+		</div>
+		<div
+			style={{
+				display: 'flex',
+				gap: 16,
+				paddingLeft: 16,
+				marginTop: 12,
+			}}
+		>
+			{labels.map((label) => (
+				<div
+					key={label}
+					style={{
+						flex: 1,
+						textAlign: 'center',
+						color: COLOR_MUTED,
+						fontSize: 20,
+					}}
+				>
+					{label}
+				</div>
+			))}
+		</div>
+	</div>
+);
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps, height} = useVideoConfig();
+
+	const data = [
+		{month: 'Jan', price: 2039},
+		{month: 'Mar', price: 2160},
+		{month: 'May', price: 2327},
+		{month: 'Jul', price: 2426},
+		{month: 'Sep', price: 2634},
+		{month: 'Nov', price: 2672},
+	];
+
+	const minPrice = 2000;
+	const maxPrice = 2800;
+	const priceRange = maxPrice - minPrice;
+	const chartHeight = height - 280;
+	const yAxisSteps = [2000, 2400, 2800];
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				padding: 60,
+				display: 'flex',
+				flexDirection: 'column',
+				fontFamily,
+			}}
+		>
+			<Title>Gold Price 2024</Title>
+
+			<div style={{display: 'flex', flex: 1}}>
+				<YAxis steps={yAxisSteps} height={chartHeight} />
+				<XAxis height={chartHeight} labels={data.map((d) => d.month)}>
+					{data.map((item, i) => {
+						const progress = spring({
+							frame: frame - i * 5 - 10,
+							fps,
+							config: {damping: 18, stiffness: 80},
+						});
+
+						const barHeight =
+							((item.price - minPrice) / priceRange) * chartHeight * progress;
+
+						return (
+							<Bar key={item.month} height={barHeight} progress={progress} />
+						);
+					})}
+				</XAxis>
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx b/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx
new file mode 100644
index 00000000..89f62ea0
--- /dev/null
+++ b/skills/remotion-best-practices/rules/assets/text-animations-typewriter.tsx
@@ -0,0 +1,100 @@
+import {
+	AbsoluteFill,
+	interpolate,
+	useCurrentFrame,
+	useVideoConfig,
+} from 'remotion';
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const FULL_TEXT = 'From prompt to motion graphics. This is Remotion.';
+const PAUSE_AFTER = 'From prompt to motion graphics.';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const CHAR_FRAMES = 2;
+const CURSOR_BLINK_FRAMES = 16;
+const PAUSE_SECONDS = 1;
+
+// Ideal composition size: 1280x720
+
+const getTypedText = ({
+	frame,
+	fullText,
+	pauseAfter,
+	charFrames,
+	pauseFrames,
+}: {
+	frame: number;
+	fullText: string;
+	pauseAfter: string;
+	charFrames: number;
+	pauseFrames: number;
+}): string => {
+	const pauseIndex = fullText.indexOf(pauseAfter);
+	const preLen =
+		pauseIndex >= 0 ? pauseIndex + pauseAfter.length : fullText.length;
+
+	let typedChars = 0;
+	if (frame < preLen * charFrames) {
+		typedChars = Math.floor(frame / charFrames);
+	} else if (frame < preLen * charFrames + pauseFrames) {
+		typedChars = preLen;
+	} else {
+		const postPhase = frame - preLen * charFrames - pauseFrames;
+		typedChars = Math.min(
+			fullText.length,
+			preLen + Math.floor(postPhase / charFrames),
+		);
+	}
+	return fullText.slice(0, typedChars);
+};
+
+const Cursor: React.FC<{
+	frame: number;
+	blinkFrames: number;
+	symbol?: string;
+}> = ({frame, blinkFrames, symbol = '\u258C'}) => {
+	const opacity = interpolate(
+		frame % blinkFrames,
+		[0, blinkFrames / 2, blinkFrames],
+		[1, 0, 1],
+		{extrapolateLeft: 'clamp', extrapolateRight: 'clamp'},
+	);
+
+	return <span style={{opacity}}>{symbol}</span>;
+};
+
+export const MyAnimation = () => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const pauseFrames = Math.round(fps * PAUSE_SECONDS);
+
+	const typedText = getTypedText({
+		frame,
+		fullText: FULL_TEXT,
+		pauseAfter: PAUSE_AFTER,
+		charFrames: CHAR_FRAMES,
+		pauseFrames,
+	});
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+					fontFamily: 'sans-serif',
+				}}
+			>
+				<span>{typedText}</span>
+				<Cursor frame={frame} blinkFrames={CURSOR_BLINK_FRAMES} />
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx b/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx
new file mode 100644
index 00000000..0aae3e29
--- /dev/null
+++ b/skills/remotion-best-practices/rules/assets/text-animations-word-highlight.tsx
@@ -0,0 +1,103 @@
+import {loadFont} from '@remotion/google-fonts/Inter';
+import React from 'react';
+import {AbsoluteFill, spring, useCurrentFrame, useVideoConfig} from 'remotion';
+
+/*
+ * Highlight a word in a sentence with a spring-animated wipe effect.
+ */
+
+// Ideal composition size: 1280x720
+
+const COLOR_BG = '#ffffff';
+const COLOR_TEXT = '#000000';
+const COLOR_HIGHLIGHT = '#A7C7E7';
+const FULL_TEXT = 'This is Remotion.';
+const HIGHLIGHT_WORD = 'Remotion';
+const FONT_SIZE = 72;
+const FONT_WEIGHT = 700;
+const HIGHLIGHT_START_FRAME = 30;
+const HIGHLIGHT_WIPE_DURATION = 18;
+
+const {fontFamily} = loadFont();
+
+const Highlight: React.FC<{
+	word: string;
+	color: string;
+	delay: number;
+	durationInFrames: number;
+}> = ({word, color, delay, durationInFrames}) => {
+	const frame = useCurrentFrame();
+	const {fps} = useVideoConfig();
+
+	const highlightProgress = spring({
+		fps,
+		frame,
+		config: {damping: 200},
+		delay,
+		durationInFrames,
+	});
+	const scaleX = Math.max(0, Math.min(1, highlightProgress));
+
+	return (
+		<span style={{position: 'relative', display: 'inline-block'}}>
+			<span
+				style={{
+					position: 'absolute',
+					left: 0,
+					right: 0,
+					top: '50%',
+					height: '1.05em',
+					transform: `translateY(-50%) scaleX(${scaleX})`,
+					transformOrigin: 'left center',
+					backgroundColor: color,
+					borderRadius: '0.18em',
+					zIndex: 0,
+				}}
+			/>
+			<span style={{position: 'relative', zIndex: 1}}>{word}</span>
+		</span>
+	);
+};
+
+export const MyAnimation = () => {
+	const highlightIndex = FULL_TEXT.indexOf(HIGHLIGHT_WORD);
+	const hasHighlight = highlightIndex >= 0;
+	const preText = hasHighlight ? FULL_TEXT.slice(0, highlightIndex) : FULL_TEXT;
+	const postText = hasHighlight
+		? FULL_TEXT.slice(highlightIndex + HIGHLIGHT_WORD.length)
+		: '';
+
+	return (
+		<AbsoluteFill
+			style={{
+				backgroundColor: COLOR_BG,
+				alignItems: 'center',
+				justifyContent: 'center',
+				fontFamily,
+			}}
+		>
+			<div
+				style={{
+					color: COLOR_TEXT,
+					fontSize: FONT_SIZE,
+					fontWeight: FONT_WEIGHT,
+				}}
+			>
+				{hasHighlight ? (
+					<>
+						<span>{preText}</span>
+						<Highlight
+							word={HIGHLIGHT_WORD}
+							color={COLOR_HIGHLIGHT}
+							delay={HIGHLIGHT_START_FRAME}
+							durationInFrames={HIGHLIGHT_WIPE_DURATION}
+						/>
+						<span>{postText}</span>
+					</>
+				) : (
+					<span>{FULL_TEXT}</span>
+				)}
+			</div>
+		</AbsoluteFill>
+	);
+};
diff --git a/skills/remotion-best-practices/rules/audio-visualization.md b/skills/remotion-best-practices/rules/audio-visualization.md
new file mode 100644
index 00000000..733b0d35
--- /dev/null
+++ b/skills/remotion-best-practices/rules/audio-visualization.md
@@ -0,0 +1,198 @@
+---
+name: audio-visualization
+description: Audio visualization patterns - spectrum bars, waveforms, bass-reactive effects
+metadata:
+  tags: audio, visualization, spectrum, waveform, bass, music, audiogram, frequency
+---
+
+# Audio Visualization in Remotion
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/media-utils
+```
+
+## Loading Audio Data
+
+Use `useWindowedAudioData()` (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:
+
+```tsx
+import { useWindowedAudioData } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("podcast.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+```
+
+## Spectrum Bar Visualization
+
+Use `visualizeAudio()` (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:
+
+```tsx
+import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("music.mp3"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+return (
+  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
+    {frequencies.map((v, i) => (
+      <div
+        key={i}
+        style={{
+          flex: 1,
+          height: `${v * 100}%`,
+          backgroundColor: "#0b84f3",
+          margin: "0 1px",
+        }}
+      />
+    ))}
+  </div>
+);
+```
+
+- `numberOfSamples` must be power of 2 (32, 64, 128, 256, 512, 1024)
+- Values range 0-1; left of array = bass, right = highs
+- Use `optimizeFor: "speed"` for Lambda or high sample counts
+
+**Important:** When passing `audioData` to child components, also pass the `frame` from the parent. Do not call `useCurrentFrame()` in each child - this causes discontinuous visualization when children are inside `<Sequence>` with offsets.
+
+## Waveform Visualization
+
+Use `visualizeAudioWaveform()` (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with `createSmoothSvgPath()` (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:
+
+```tsx
+import {
+  createSmoothSvgPath,
+  useWindowedAudioData,
+  visualizeAudioWaveform,
+} from "@remotion/media-utils";
+import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { width, fps } = useVideoConfig();
+const HEIGHT = 200;
+
+const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
+  src: staticFile("voice.wav"),
+  frame,
+  fps,
+  windowInSeconds: 30,
+});
+
+if (!audioData) {
+  return null;
+}
+
+const waveform = visualizeAudioWaveform({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 256,
+  windowInSeconds: 0.5,
+  dataOffsetInSeconds,
+});
+
+const path = createSmoothSvgPath({
+  points: waveform.map((y, i) => ({
+    x: (i / (waveform.length - 1)) * width,
+    y: HEIGHT / 2 + (y * HEIGHT) / 2,
+  })),
+});
+
+return (
+  <svg width={width} height={HEIGHT}>
+    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
+  </svg>
+);
+```
+
+## Bass-Reactive Effects
+
+Extract low frequencies for beat-reactive animations:
+
+```tsx
+const frequencies = visualizeAudio({
+  fps,
+  frame,
+  audioData,
+  numberOfSamples: 128,
+  optimizeFor: "speed",
+  dataOffsetInSeconds,
+});
+
+const lowFrequencies = frequencies.slice(0, 32);
+const bassIntensity =
+  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;
+
+const scale = 1 + bassIntensity * 0.5;
+const opacity = Math.min(0.6, bassIntensity * 0.8);
+```
+
+## Volume-Based Waveform
+
+Use `getWaveformPortion()` (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:
+
+```tsx
+import { getWaveformPortion } from "@remotion/media-utils";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+const currentTimeInSeconds = frame / fps;
+
+const waveform = getWaveformPortion({
+  audioData,
+  startTimeInSeconds: currentTimeInSeconds,
+  durationInSeconds: 5,
+  numberOfSamples: 50,
+});
+
+// Returns array of { index, amplitude } objects (amplitude: 0-1)
+waveform.map((bar) => (
+  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
+));
+```
+
+## Postprocessing
+
+Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:
+
+```tsx
+const minDb = -100;
+const maxDb = -30;
+
+const scaled = frequencies.map((value) => {
+  const db = 20 * Math.log10(value);
+  return (db - minDb) / (maxDb - minDb);
+});
+```
diff --git a/skills/remotion-best-practices/rules/audio.md b/skills/remotion-best-practices/rules/audio.md
new file mode 100644
index 00000000..1097c70e
--- /dev/null
+++ b/skills/remotion-best-practices/rules/audio.md
@@ -0,0 +1,169 @@
+---
+name: audio
+description: Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+metadata:
+  tags: audio, media, trim, volume, speed, loop, pitch, mute, sound, sfx
+---
+
+# Using audio in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/media
+```
+
+## Importing Audio
+
+Use `<Audio>` from `@remotion/media` to add audio to your composition.
+
+```tsx
+import { Audio } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Audio src={staticFile("audio.mp3")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Audio src="https://remotion.media/audio.mp3" />
+```
+
+By default, audio plays from the start, at full volume and full length.
+Multiple audio tracks can be layered by adding multiple `<Audio>` components.
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the audio. Values are in frames.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+The audio still starts playing at the beginning of the composition - only the specified portion is played.
+
+## Delaying
+
+Wrap the audio in a `<Sequence>` to delay when it starts:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Audio } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Audio src={staticFile("audio.mp3")} />
+  </Sequence>
+);
+```
+
+The audio will start playing after 1 second.
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Audio src={staticFile("audio.mp3")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+The value of `f` starts at 0 when the audio begins to play, not the composition frame.
+
+## Muting
+
+Use `muted` to silence the audio. It can be set dynamically:
+
+```tsx
+const frame = useCurrentFrame();
+const { fps } = useVideoConfig();
+
+return (
+  <Audio
+    src={staticFile("audio.mp3")}
+    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
+  />
+);
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
+<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the audio indefinitely:
+
+```tsx
+<Audio src={staticFile("audio.mp3")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (default)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Audio
+  src={staticFile("audio.mp3")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/skills/remotion-best-practices/rules/calculate-metadata.md b/skills/remotion-best-practices/rules/calculate-metadata.md
new file mode 100644
index 00000000..54df5ffb
--- /dev/null
+++ b/skills/remotion-best-practices/rules/calculate-metadata.md
@@ -0,0 +1,134 @@
+---
+name: calculate-metadata
+description: Dynamically set composition duration, dimensions, and props
+metadata:
+  tags: calculateMetadata, duration, dimensions, props, dynamic
+---
+
+# Using calculateMetadata
+
+Use `calculateMetadata` on a `<Composition>` to dynamically set duration, dimensions, and transform props before rendering.
+
+```tsx
+<Composition
+  id="MyComp"
+  component={MyComponent}
+  durationInFrames={300}
+  fps={30}
+  width={1920}
+  height={1080}
+  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
+  calculateMetadata={calculateMetadata}
+/>
+```
+
+## Setting duration based on a video
+
+Use the [`getVideoDuration`](./get-video-duration.md) and [`getVideoDimensions`](./get-video-dimensions.md) skills to get the video duration and dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durationInSeconds = await getVideoDuration(props.videoSrc);
+
+  return {
+    durationInFrames: Math.ceil(durationInSeconds * 30),
+  };
+};
+```
+
+## Matching dimensions of a video
+
+Use the [`getVideoDimensions`](./get-video-dimensions.md) skill to get the video dimensions:
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+import { getVideoDuration } from "./get-video-duration";
+import { getVideoDimensions } from "./get-video-dimensions";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const dimensions = await getVideoDimensions(props.videoSrc);
+
+  return {
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+};
+```
+
+## Setting duration based on multiple videos
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const metadataPromises = props.videos.map((video) =>
+    getVideoDuration(video.src),
+  );
+  const allMetadata = await Promise.all(metadataPromises);
+
+  const totalDuration = allMetadata.reduce(
+    (sum, durationInSeconds) => sum + durationInSeconds,
+    0,
+  );
+
+  return {
+    durationInFrames: Math.ceil(totalDuration * 30),
+  };
+};
+```
+
+## Setting a default outName
+
+Set the default output filename based on props:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultOutName: `video-${props.id}`, // .mp4 is added automatically
+  };
+};
+```
+
+## Transforming props
+
+Fetch data or transform props before rendering:
+
+```tsx
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+  abortSignal,
+}) => {
+  const response = await fetch(props.dataUrl, { signal: abortSignal });
+  const data = await response.json();
+
+  return {
+    props: {
+      ...props,
+      fetchedData: data,
+    },
+  };
+};
+```
+
+The `abortSignal` cancels stale requests when props change in the Studio.
+
+## Return value
+
+All fields are optional. Returned values override the `<Composition>` props:
+
+- `durationInFrames`: Number of frames
+- `width`: Composition width in pixels
+- `height`: Composition height in pixels
+- `fps`: Frames per second
+- `props`: Transformed props passed to the component
+- `defaultOutName`: Default output filename
+- `defaultCodec`: Default codec for rendering
diff --git a/skills/remotion-best-practices/rules/compositions.md b/skills/remotion-best-practices/rules/compositions.md
new file mode 100644
index 00000000..4f6b8656
--- /dev/null
+++ b/skills/remotion-best-practices/rules/compositions.md
@@ -0,0 +1,133 @@
+---
+name: compositions
+description: Defining compositions, stills, folders, default props and dynamic metadata
+metadata:
+  tags: composition, still, folder, props, metadata
+---
+
+A `<Composition>` defines the component, width, height, fps and duration of a renderable video.
+
+## Default Props
+
+Pass `defaultProps` to provide initial values for your component.  
+Values must be JSON-serializable (`Date`, `Map`, `Set`, and `staticFile()` are supported).
+
+```tsx
+import { Composition } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={
+        {
+          title: "Hello World",
+          color: "#ff0000",
+        } satisfies MyCompositionProps
+      }
+    />
+  );
+};
+```
+
+Use `type` declarations for props rather than `interface` to ensure `defaultProps` type safety.
+
+## Folders
+
+Use `<Folder>` to organize compositions in the sidebar.  
+Folder names can only contain letters, numbers, and hyphens.
+
+```tsx
+import { Composition, Folder } from "remotion";
+
+export const RemotionRoot = () => {
+  return (
+    <>
+      <Folder name="Marketing">
+        <Composition id="Promo" /* ... */ />
+        <Composition id="Ad" /* ... */ />
+      </Folder>
+      <Folder name="Social">
+        <Folder name="Instagram">
+          <Composition id="Story" /* ... */ />
+          <Composition id="Reel" /* ... */ />
+        </Folder>
+      </Folder>
+    </>
+  );
+};
+```
+
+## Stills
+
+Use `<Still>` for single-frame images. It does not require `durationInFrames` or `fps`.
+
+```tsx
+import { Still } from "remotion";
+import { Thumbnail } from "./Thumbnail";
+
+export const RemotionRoot = () => {
+  return (
+    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
+  );
+};
+```
+
+## Calculate Metadata
+
+Use `calculateMetadata` to make dimensions, duration, or props dynamic based on data.
+
+```tsx
+import { Composition, CalculateMetadataFunction } from "remotion";
+import { MyComposition, MyCompositionProps } from "./MyComposition";
+
+const calculateMetadata: CalculateMetadataFunction<
+  MyCompositionProps
+> = async ({ props, abortSignal }) => {
+  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
+    signal: abortSignal,
+  }).then((res) => res.json());
+
+  return {
+    durationInFrames: Math.ceil(data.duration * 30),
+    props: {
+      ...props,
+      videoUrl: data.url,
+    },
+  };
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComposition}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ videoId: "abc123" }}
+      calculateMetadata={calculateMetadata}
+    />
+  );
+};
+```
+
+The function can return `props`, `durationInFrames`, `width`, `height`, `fps`, and codec-related defaults. It runs once before rendering begins.
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/skills/remotion-best-practices/rules/display-captions.md b/skills/remotion-best-practices/rules/display-captions.md
new file mode 100644
index 00000000..f9cb0f05
--- /dev/null
+++ b/skills/remotion-best-practices/rules/display-captions.md
@@ -0,0 +1,184 @@
+---
+name: display-captions
+description: Displaying captions in Remotion with TikTok-style pages and word highlighting
+metadata:
+  tags: captions, subtitles, display, tiktok, highlight
+---
+
+# Displaying captions in Remotion
+
+This guide explains how to display captions in Remotion, assuming you already have captions in the [`Caption`](https://www.remotion.dev/docs/captions/caption) format.
+
+## Prerequisites
+
+Read [Transcribing audio](transcribe-captions.md) for how to generate captions.
+
+First, the [`@remotion/captions`](https://www.remotion.dev/docs/captions) package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions
+```
+
+## Fetching captions
+
+First, fetch your captions JSON file. Use [`useDelayRender()`](https://www.remotion.dev/docs/use-delay-render) to hold the render until the captions are loaded:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      // Assuming captions.json is in the public/ folder.
+      const response = await fetch(staticFile("captions123.json"));
+      const data = await response.json();
+      setCaptions(data);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
+};
+```
+
+## Creating pages
+
+Use `createTikTokStyleCaptions()` to group captions into pages. The `combineTokensWithinMilliseconds` option controls how many words appear at once:
+
+```tsx
+import { useMemo } from "react";
+import { createTikTokStyleCaptions } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+// How often captions should switch (in milliseconds)
+// Higher values = more words per page
+// Lower values = fewer words (more word-by-word)
+const SWITCH_CAPTIONS_EVERY_MS = 1200;
+
+const { pages } = useMemo(() => {
+  return createTikTokStyleCaptions({
+    captions,
+    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
+  });
+}, [captions]);
+```
+
+## Rendering with Sequences
+
+Map over the pages and render each one in a `<Sequence>`. Calculate the start frame and duration from the page timing:
+
+```tsx
+import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const CaptionedContent: React.FC = () => {
+  const { fps } = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      {pages.map((page, index) => {
+        const nextPage = pages[index + 1] ?? null;
+        const startFrame = (page.startMs / 1000) * fps;
+        const endFrame = Math.min(
+          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
+          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
+        );
+        const durationInFrames = endFrame - startFrame;
+
+        if (durationInFrames <= 0) {
+          return null;
+        }
+
+        return (
+          <Sequence
+            key={index}
+            from={startFrame}
+            durationInFrames={durationInFrames}
+          >
+            <CaptionPage page={page} />
+          </Sequence>
+        );
+      })}
+    </AbsoluteFill>
+  );
+};
+```
+
+## White-space preservation
+
+The captions are whitespace sensitive. You should include spaces in the `text` field before each word. Use `whiteSpace: "pre"` to preserve the whitespace in the captions.
+
+## Separate component for captions
+
+Put captioning logic in a separate component.  
+Make a new file for it.
+
+## Word highlighting
+
+A caption page contains `tokens` which you can use to highlight the currently spoken word:
+
+```tsx
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+const HIGHLIGHT_COLOR = "#39E508";
+
+const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  // Current time relative to the start of the sequence
+  const currentTimeMs = (frame / fps) * 1000;
+  // Convert to absolute time by adding the page start
+  const absoluteTimeMs = page.startMs + currentTimeMs;
+
+  return (
+    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
+      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
+        {page.tokens.map((token) => {
+          const isActive =
+            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;
+
+          return (
+            <span
+              key={token.fromMs}
+              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
+            >
+              {token.text}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+```
+
+## Display captions alongside video content
+
+By default, put the captions alongside the video content, so the captions are in sync.  
+For each video, make a new captions JSON file.
+
+```tsx
+<AbsoluteFill>
+  <Video src={staticFile("video.mp4")} />
+  <CaptionPage page={page} />
+</AbsoluteFill>
+```
diff --git a/skills/remotion-best-practices/rules/ffmpeg.md b/skills/remotion-best-practices/rules/ffmpeg.md
new file mode 100644
index 00000000..d3fd100c
--- /dev/null
+++ b/skills/remotion-best-practices/rules/ffmpeg.md
@@ -0,0 +1,34 @@
+---
+name: ffmpeg
+description: Using FFmpeg and FFprobe in Remotion
+metadata:
+  tags: ffmpeg, ffprobe, video, trimming
+---
+
+## FFmpeg in Remotion
+
+`ffmpeg` and `ffprobe` do not need to be installed. They are available via the `npx remotion ffmpeg` and `npx remotion ffprobe`:
+
+```bash
+npx remotion ffmpeg -i input.mp4 output.mp3
+npx remotion ffprobe input.mp4
+```
+
+### Trimming videos
+
+You have 2 options for trimming videos:
+
+1. **Preferred**: Use the `trimBefore` and `trimAfter` props of the `<Video>` component. This is non-destructive, requires no re-encoding, and you can change the trim at any time.
+
+```tsx
+import {Video} from '@remotion/media';
+
+<Video src={staticFile('video.mp4')} trimBefore={5 * fps} trimAfter={10 * fps} />;
+```
+
+2. Use the FFmpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video. Only use this if you need a standalone trimmed file (e.g. for upload or external use).
+
+```bash
+# Re-encodes from the exact frame
+npx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4
+```
diff --git a/skills/remotion-best-practices/rules/get-audio-duration.md b/skills/remotion-best-practices/rules/get-audio-duration.md
new file mode 100644
index 00000000..35ef7471
--- /dev/null
+++ b/skills/remotion-best-practices/rules/get-audio-duration.md
@@ -0,0 +1,58 @@
+---
+name: get-audio-duration
+description: Getting the duration of an audio file in seconds with Mediabunny
+metadata:
+  tags: duration, audio, length, time, seconds, mp3, wav
+---
+
+# Getting audio duration with Mediabunny
+
+Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.
+
+## Getting audio duration
+
+```tsx title="get-audio-duration.ts"
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getAudioDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getAudioDuration("https://remotion.media/audio.mp3");
+console.log(duration); // e.g. 180.5 (seconds)
+```
+
+## Using with staticFile in Remotion
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getAudioDuration(staticFile("audio.mp3"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+```
diff --git a/skills/remotion-best-practices/rules/get-video-dimensions.md b/skills/remotion-best-practices/rules/get-video-dimensions.md
new file mode 100644
index 00000000..746c09fb
--- /dev/null
+++ b/skills/remotion-best-practices/rules/get-video-dimensions.md
@@ -0,0 +1,68 @@
+---
+name: get-video-dimensions
+description: Getting the width and height of a video file with Mediabunny
+metadata:
+  tags: dimensions, width, height, resolution, size, video
+---
+
+# Getting video dimensions with Mediabunny
+
+Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video dimensions
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDimensions = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (!videoTrack) {
+    throw new Error("No video track found");
+  }
+
+  return {
+    width: videoTrack.displayWidth,
+    height: videoTrack.displayHeight,
+  };
+};
+```
+
+## Usage
+
+```tsx
+const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
+console.log(dimensions.width); // e.g. 1920
+console.log(dimensions.height); // e.g. 1080
+```
+
+## Using with local files
+
+For local files, use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const videoTrack = await input.getPrimaryVideoTrack();
+const width = videoTrack.displayWidth;
+const height = videoTrack.displayHeight;
+```
+
+## Using with staticFile in Remotion
+
+```tsx
+import { staticFile } from "remotion";
+
+const dimensions = await getVideoDimensions(staticFile("video.mp4"));
+```
diff --git a/skills/remotion-best-practices/rules/get-video-duration.md b/skills/remotion-best-practices/rules/get-video-duration.md
new file mode 100644
index 00000000..10ab735d
--- /dev/null
+++ b/skills/remotion-best-practices/rules/get-video-duration.md
@@ -0,0 +1,60 @@
+---
+name: get-video-duration
+description: Getting the duration of a video file in seconds with Mediabunny
+metadata:
+  tags: duration, video, length, time, seconds
+---
+
+# Getting video duration with Mediabunny
+
+Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.
+
+## Getting video duration
+
+```tsx
+import { Input, ALL_FORMATS, UrlSource } from "mediabunny";
+
+export const getVideoDuration = async (src: string) => {
+  const input = new Input({
+    formats: ALL_FORMATS,
+    source: new UrlSource(src, {
+      getRetryDelay: () => null,
+    }),
+  });
+
+  const durationInSeconds = await input.computeDuration();
+  return durationInSeconds;
+};
+```
+
+## Usage
+
+```tsx
+const duration = await getVideoDuration("https://remotion.media/video.mp4");
+console.log(duration); // e.g. 10.5 (seconds)
+```
+
+## Video files from the public/ directory
+
+Make sure to wrap the file path in `staticFile()`:
+
+```tsx
+import { staticFile } from "remotion";
+
+const duration = await getVideoDuration(staticFile("video.mp4"));
+```
+
+## In Node.js and Bun
+
+Use `FileSource` instead of `UrlSource`:
+
+```tsx
+import { Input, ALL_FORMATS, FileSource } from "mediabunny";
+
+const input = new Input({
+  formats: ALL_FORMATS,
+  source: new FileSource(file), // File object from input or drag-drop
+});
+
+const durationInSeconds = await input.computeDuration();
+```
diff --git a/skills/remotion-best-practices/rules/gifs.md b/skills/remotion-best-practices/rules/gifs.md
new file mode 100644
index 00000000..042647f6
--- /dev/null
+++ b/skills/remotion-best-practices/rules/gifs.md
@@ -0,0 +1,141 @@
+---
+name: gif
+description: Displaying GIFs, APNG, AVIF and WebP in Remotion
+metadata:
+  tags: gif, animation, images, animated, apng, avif, webp
+---
+
+# Using Animated images in Remotion
+
+## Basic usage
+
+Use `<AnimatedImage>` to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:
+
+```tsx
+import { AnimatedImage, staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return (
+    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
+  );
+};
+```
+
+Remote URLs are also supported (must have CORS enabled):
+
+```tsx
+<AnimatedImage
+  src="https://example.com/animation.gif"
+  width={500}
+  height={500}
+/>
+```
+
+## Sizing and fit
+
+Control how the image fills its container with the `fit` prop:
+
+```tsx
+// Stretch to fill (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />
+
+// Maintain aspect ratio, fit inside container
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />
+
+// Fill container, crop if needed
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />
+```
+
+## Playback speed
+
+Use `playbackRate` to control the animation speed:
+
+```tsx
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}
+```
+
+## Looping behavior
+
+Control what happens when the animation finishes:
+
+```tsx
+// Loop indefinitely (default)
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />
+
+// Play once, show final frame
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />
+
+// Play once, then clear canvas
+<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />
+```
+
+## Styling
+
+Use the `style` prop for additional CSS (use `width` and `height` props for sizing):
+
+```tsx
+<AnimatedImage
+  src={staticFile("animation.gif")}
+  width={500}
+  height={500}
+  style={{
+    borderRadius: 20,
+    position: "absolute",
+    top: 100,
+    left: 50,
+  }}
+/>
+```
+
+## Getting GIF duration
+
+Use `getGifDurationInSeconds()` from `@remotion/gif` to get the duration of a GIF.
+
+```bash
+npx remotion add @remotion/gif
+```
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+console.log(duration); // e.g. 2.5
+```
+
+This is useful for setting the composition duration to match the GIF:
+
+```tsx
+import { getGifDurationInSeconds } from "@remotion/gif";
+import { staticFile, CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
+  return {
+    durationInFrames: Math.ceil(duration * 30),
+  };
+};
+```
+
+## Alternative
+
+If `<AnimatedImage>` does not work (only supported in Chrome and Firefox), you can use `<Gif>` from `@remotion/gif` instead.
+
+```bash
+npx remotion add @remotion/gif # If project uses npm
+bunx remotion add @remotion/gif # If project uses bun
+yarn remotion add @remotion/gif # If project uses yarn
+pnpm exec remotion add @remotion/gif # If project uses pnpm
+```
+
+```tsx
+import { Gif } from "@remotion/gif";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
+};
+```
+
+The `<Gif>` component has the same props as `<AnimatedImage>` but only supports GIF files.
diff --git a/skills/remotion-best-practices/rules/google-fonts.md b/skills/remotion-best-practices/rules/google-fonts.md
new file mode 100644
index 00000000..87c07697
--- /dev/null
+++ b/skills/remotion-best-practices/rules/google-fonts.md
@@ -0,0 +1,72 @@
+---
+name: fonts
+description: Loading Google Fonts and local fonts in Remotion
+metadata:
+  tags: fonts, google-fonts, typography, text
+---
+
+# Using fonts in Remotion
+
+## Google Fonts with @remotion/google-fonts
+
+The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.
+
+### Prerequisites
+
+First, the @remotion/google-fonts package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/google-fonts # If project uses npm
+bunx remotion add @remotion/google-fonts # If project uses bun
+yarn remotion add @remotion/google-fonts # If project uses yarn
+pnpm exec remotion add @remotion/google-fonts # If project uses pnpm
+```
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Lobster";
+
+const { fontFamily } = loadFont();
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily }}>Hello World</div>;
+};
+```
+
+Preferrably, specify only needed weights and subsets to reduce file size:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Roboto";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+```
+
+## Using in components
+
+Call `loadFont()` at the top level of your component or in a separate file that's imported early:
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Montserrat";
+
+const { fontFamily } = loadFont("normal", {
+  weights: ["400", "700"],
+  subsets: ["latin"],
+});
+
+export const Title: React.FC<{ text: string }> = ({ text }) => {
+  return (
+    <h1
+      style={{
+        fontFamily,
+        fontSize: 80,
+        fontWeight: "bold",
+      }}
+    >
+      {text}
+    </h1>
+  );
+};
+```
diff --git a/skills/remotion-best-practices/rules/html-in-canvas.md b/skills/remotion-best-practices/rules/html-in-canvas.md
new file mode 100644
index 00000000..def5a980
--- /dev/null
+++ b/skills/remotion-best-practices/rules/html-in-canvas.md
@@ -0,0 +1,122 @@
+# Using `<HtmlInCanvas>` in Remotion
+
+Renders children into a `<canvas>` so you can post-process them with the Canvas 2D API or WebGL.
+
+Only works in Chrome 149+ with the `chrome://flags/#canvas-draw-element` flag enabled.  
+Give the user a notice.
+
+## Nesting
+
+Do not nest `<HtmlInCanvas>` inside another `<HtmlInCanvas>`. Remotion throws:
+
+```
+<HtmlInCanvas> effects cannot be nested together. Chrome will only display the outer effect. Consider merging the effects into one if you can.
+```
+
+## Enabling WebGL during renders
+
+If you make use of WebGL during renders, you need to enable it:
+
+From the CLI:
+
+```bash
+npx remotion render --gl=angle
+```
+
+Set it as the default for Studio and CLI (advised):
+
+```ts
+import { Config } from "@remotion/cli/config";
+
+Config.setChromiumOpenGlRenderer("angle");
+```
+
+## Basic usage
+
+By default, draws to canvas with no effect applied:
+
+```tsx
+import { HtmlInCanvas } from "remotion";
+
+export const MyComp = () => {
+  return (
+    <HtmlInCanvas width={1280} height={720}>
+      <div style={{ fontSize: 80 }}>Hello</div>
+    </HtmlInCanvas>
+  );
+};
+```
+
+## 2D effect with `onPaint`
+
+`onPaint` runs whenever the content updates. Call `ctx.drawElementImage(elementImage, 0, 0)` to draw the captured DOM, and assign the returned transform to `element.style.transform` so DOM selection still aligns with the painted output.
+
+```tsx
+import {
+  AbsoluteFill,
+  HtmlInCanvas,
+  type HtmlInCanvasOnPaint,
+  useCurrentFrame,
+  useVideoConfig,
+} from "remotion";
+import { useCallback } from "react";
+
+export const Blur = () => {
+  const frame = useCurrentFrame();
+  const { width, height, fps } = useVideoConfig();
+
+  const onPaint: HtmlInCanvasOnPaint = useCallback(
+    ({ canvas, element, elementImage }) => {
+      const ctx = canvas.getContext("2d");
+      if (!ctx) throw new Error("Failed to acquire 2D context");
+
+      const blurPx = 4 + 18 * (0.5 + 0.5 * Math.sin((frame / fps) * Math.PI));
+
+      ctx.reset();
+      ctx.filter = `blur(${blurPx}px)`;
+      const transform = ctx.drawElementImage(elementImage, 0, 0);
+      element.style.transform = transform.toString();
+    },
+    [frame, fps],
+  );
+
+  return (
+    <HtmlInCanvas width={width} height={height} onPaint={onPaint}>
+      <AbsoluteFill style={{ justifyContent: "center", alignItems: "center", fontSize: 120 }}>
+        <h1>Hello</h1>
+      </AbsoluteFill>
+    </HtmlInCanvas>
+  );
+};
+```
+
+## WebGL effects
+
+For WebGL, set up the context, program, and texture in `onInit` and return a cleanup function. Inside `onPaint`, upload the captured DOM with `gl.texElementImage2D(...)` and draw.
+
+```tsx
+const onInit: HtmlInCanvasOnInit = useCallback(({ canvas }) => {
+  const gl = canvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true });
+  if (!gl) {
+    throw new Error(
+      "WebGL2 unavailable. Try rendering with the --gl=angle option. See https://remotion.dev/docs/gl-options.",
+    );
+  }
+  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
+  // compile program, create texture, set up VAO...
+  return () => {
+    // delete program, texture, buffers...
+  };
+}, []);
+
+const onPaint: HtmlInCanvasOnPaint = useCallback(({ elementImage }) => {
+  gl.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, elementImage);
+  gl.drawArrays(gl.TRIANGLES, 0, 6);
+}, []);
+```
+
+For a fully working minimal example, see https://github.com/remotion-dev/remotion/blob/main/packages/docs/components/demos/HtmlInCanvasDocsDemoWebGL.tsx.
+
+## Async `onPaint`
+
+`onPaint` may be `async`. Remotion holds the frame open via `delayRender()` until the promise resolves. Useful for multi-pass effects with `createImageBitmap`.
diff --git a/skills/remotion-best-practices/rules/images.md b/skills/remotion-best-practices/rules/images.md
new file mode 100644
index 00000000..6882b265
--- /dev/null
+++ b/skills/remotion-best-practices/rules/images.md
@@ -0,0 +1,71 @@
+## Sizing and positioning
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Img
+  src={staticFile("photo.png")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Dynamic image paths
+
+Use template literals for dynamic file references:
+
+```tsx
+import { Img, staticFile, useCurrentFrame } from "remotion";
+
+const frame = useCurrentFrame();
+
+// Image sequence
+<Img src={staticFile(`frames/frame${frame}.png`)} />
+
+// Selecting based on props
+<Img src={staticFile(`avatars/${props.userId}.png`)} />
+
+// Conditional images
+<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />
+```
+
+This pattern is useful for:
+
+- Image sequences (frame-by-frame animations)
+- User-specific avatars or profile images
+- Theme-based icons
+- State-dependent graphics
+
+## Getting image dimensions
+
+Use `getImageDimensions()` to get the dimensions of an image:
+
+```tsx
+import { getImageDimensions, staticFile } from "remotion";
+
+const { width, height } = await getImageDimensions(staticFile("photo.png"));
+```
+
+This is useful for calculating aspect ratios or sizing compositions:
+
+```tsx
+import {
+  getImageDimensions,
+  staticFile,
+  CalculateMetadataFunction,
+} from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction = async () => {
+  const { width, height } = await getImageDimensions(staticFile("photo.png"));
+  return {
+    width,
+    height,
+  };
+};
+```
diff --git a/skills/remotion-best-practices/rules/import-srt-captions.md b/skills/remotion-best-practices/rules/import-srt-captions.md
new file mode 100644
index 00000000..333c9621
--- /dev/null
+++ b/skills/remotion-best-practices/rules/import-srt-captions.md
@@ -0,0 +1,69 @@
+---
+name: import-srt-captions
+description: Importing .srt subtitle files into Remotion using @remotion/captions
+metadata:
+  tags: captions, subtitles, srt, import, parse
+---
+
+# Importing .srt subtitles into Remotion
+
+If you have an existing `.srt` subtitle file, you can import it into Remotion using `parseSrt()` from `@remotion/captions`.
+
+If you don't have a .srt file, read [Transcribing audio](transcribe-captions.md) for how to generate captions instead.
+
+## Prerequisites
+
+First, the @remotion/captions package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/captions # If project uses npm
+bunx remotion add @remotion/captions # If project uses bun
+yarn remotion add @remotion/captions # If project uses yarn
+pnpm exec remotion add @remotion/captions # If project uses pnpm
+```
+
+## Reading an .srt file
+
+Use `staticFile()` to reference an `.srt` file in your `public` folder, then fetch and parse it:
+
+```tsx
+import { useState, useEffect, useCallback } from "react";
+import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
+import { parseSrt } from "@remotion/captions";
+import type { Caption } from "@remotion/captions";
+
+export const MyComponent: React.FC = () => {
+  const [captions, setCaptions] = useState<Caption[] | null>(null);
+  const { delayRender, continueRender, cancelRender } = useDelayRender();
+  const [handle] = useState(() => delayRender());
+
+  const fetchCaptions = useCallback(async () => {
+    try {
+      const response = await fetch(staticFile("subtitles.srt"));
+      const text = await response.text();
+      const { captions: parsed } = parseSrt({ input: text });
+      setCaptions(parsed);
+      continueRender(handle);
+    } catch (e) {
+      cancelRender(e);
+    }
+  }, [continueRender, cancelRender, handle]);
+
+  useEffect(() => {
+    fetchCaptions();
+  }, [fetchCaptions]);
+
+  if (!captions) {
+    return null;
+  }
+
+  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
+};
+```
+
+Remote URLs are also supported - you can `fetch()` a remote file via URL instead of using `staticFile()`.
+
+## Using imported captions
+
+Once parsed, the captions are in the `Caption` format and can be used with all `@remotion/captions` utilities.
diff --git a/skills/remotion-best-practices/rules/light-leaks.md b/skills/remotion-best-practices/rules/light-leaks.md
new file mode 100644
index 00000000..354b9566
--- /dev/null
+++ b/skills/remotion-best-practices/rules/light-leaks.md
@@ -0,0 +1,73 @@
+---
+name: light-leaks
+description: Light leak overlay effects for Remotion using @remotion/light-leaks.
+metadata:
+  tags: light-leaks, overlays, effects, transitions
+---
+
+## Light Leaks
+
+This only works from Remotion 4.0.415 and up. Use `npx remotion versions` to check your Remotion version and `npx remotion upgrade` to upgrade your Remotion version.
+
+`<LightLeak>` from `@remotion/light-leaks` renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.
+
+Typically used inside a `<TransitionSeries.Overlay>` to play over the cut point between two scenes. See the **transitions** rule for `<TransitionSeries>` and overlay usage.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/light-leaks
+```
+
+## Basic usage with TransitionSeries
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Props
+
+- `durationInFrames?` — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
+- `seed?` — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: `0`.
+- `hueShift?` — rotates the hue in degrees (`0`–`360`). Default: `0` (yellow-to-orange). `120` = green, `240` = blue.
+
+## Customizing the look
+
+```tsx
+import { LightLeak } from "@remotion/light-leaks";
+
+// Blue-tinted light leak with a different pattern
+<LightLeak seed={5} hueShift={240} />;
+
+// Green-tinted light leak
+<LightLeak seed={2} hueShift={120} />;
+```
+
+## Standalone usage
+
+`<LightLeak>` can also be used outside of `<TransitionSeries>`, for example as a decorative overlay in any composition:
+
+```tsx
+import { AbsoluteFill } from "remotion";
+import { LightLeak } from "@remotion/light-leaks";
+
+const MyComp: React.FC = () => (
+  <AbsoluteFill>
+    <MyContent />
+    <LightLeak durationInFrames={60} seed={3} />
+  </AbsoluteFill>
+);
+```
diff --git a/skills/remotion-best-practices/rules/local-fonts.md b/skills/remotion-best-practices/rules/local-fonts.md
new file mode 100644
index 00000000..30dce5fb
--- /dev/null
+++ b/skills/remotion-best-practices/rules/local-fonts.md
@@ -0,0 +1,65 @@
+For local font files, use the `@remotion/fonts` package.
+
+### Prerequisites
+
+First, install @remotion/fonts:
+
+```bash
+npx remotion add @remotion/fonts # If project uses npm
+bunx remotion add @remotion/fonts # If project uses bun
+yarn remotion add @remotion/fonts # If project uses yarn
+pnpm exec remotion add @remotion/fonts # If project uses pnpm
+```
+
+### Loading a local font
+
+Place your font file in the `public/` folder and use `loadFont()`:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await loadFont({
+  family: "MyFont",
+  url: staticFile("MyFont-Regular.woff2"),
+});
+
+export const MyComposition = () => {
+  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
+};
+```
+
+### Loading multiple weights
+
+Load each weight separately with the same family name:
+
+```tsx
+import { loadFont } from "@remotion/fonts";
+import { staticFile } from "remotion";
+
+await Promise.all([
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Regular.woff2"),
+    weight: "400",
+  }),
+  loadFont({
+    family: "Inter",
+    url: staticFile("Inter-Bold.woff2"),
+    weight: "700",
+  }),
+]);
+```
+
+### Available options
+
+```tsx
+loadFont({
+  family: "MyFont", // Required: name to use in CSS
+  url: staticFile("font.woff2"), // Required: font file URL
+  format: "woff2", // Optional: auto-detected from extension
+  weight: "400", // Optional: font weight
+  style: "normal", // Optional: normal or italic
+  display: "block", // Optional: font-display behavior
+});
+```
diff --git a/skills/remotion-best-practices/rules/lottie.md b/skills/remotion-best-practices/rules/lottie.md
new file mode 100644
index 00000000..4b0c4ee5
--- /dev/null
+++ b/skills/remotion-best-practices/rules/lottie.md
@@ -0,0 +1,70 @@
+---
+name: lottie
+description: Embedding Lottie animations in Remotion.
+metadata:
+  category: Animation
+---
+
+# Using Lottie Animations in Remotion
+
+## Prerequisites
+
+First, the @remotion/lottie package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/lottie # If project uses npm
+bunx remotion add @remotion/lottie # If project uses bun
+yarn remotion add @remotion/lottie # If project uses yarn
+pnpm exec remotion add @remotion/lottie # If project uses pnpm
+```
+
+## Displaying a Lottie file
+
+To import a Lottie animation:
+
+- Fetch the Lottie asset
+- Wrap the loading process in `delayRender()` and `continueRender()`
+- Save the animation data in a state
+- Render the Lottie animation using the `Lottie` component from the `@remotion/lottie` package
+
+```tsx
+import { Lottie, LottieAnimationData } from "@remotion/lottie";
+import { useEffect, useState } from "react";
+import { cancelRender, continueRender, delayRender } from "remotion";
+
+export const MyAnimation = () => {
+  const [handle] = useState(() => delayRender("Loading Lottie animation"));
+
+  const [animationData, setAnimationData] =
+    useState<LottieAnimationData | null>(null);
+
+  useEffect(() => {
+    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
+      .then((data) => data.json())
+      .then((json) => {
+        setAnimationData(json);
+        continueRender(handle);
+      })
+      .catch((err) => {
+        cancelRender(err);
+      });
+  }, [handle]);
+
+  if (!animationData) {
+    return null;
+  }
+
+  return <Lottie animationData={animationData} />;
+};
+```
+
+## Styling and animating
+
+Lottie supports the `style` prop to allow styles and animations:
+
+```tsx
+return (
+  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
+);
+```
diff --git a/skills/remotion-best-practices/rules/maplibre.md b/skills/remotion-best-practices/rules/maplibre.md
new file mode 100644
index 00000000..1fb2664d
--- /dev/null
+++ b/skills/remotion-best-practices/rules/maplibre.md
@@ -0,0 +1,458 @@
+---
+name: maps
+description: Make deterministic Remotion map animations with MapLibre GL JS and Turf. Use for animated routes, flyovers, map markers, labels, and camera movement.
+metadata:
+  tags: map, map animation, maplibre, turf, geojson, route animation
+---
+
+Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.
+
+## Core rules
+
+- Prefer `@turf/turf` for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
+- Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM `Marker` elements unless the user specifically asks for HTML markers.
+- Disable non-deterministic map behavior: `interactive: false`, `fadeDuration: 0`.
+- Use `delayRender()` / `continueRender()` around map loading and per-frame map updates.
+- Before continuing the initial render, add sources/layers, apply the frame-0 camera with `jumpTo()`, then wait for `idle`.
+- Do not add a `mapInstance.remove()` cleanup function; it can interfere with Remotion's render lifecycle.
+- Use standard MapLibre style JSON URLs and layer/source APIs.
+- Do not install `@types/maplibre-gl`; MapLibre ships its own types.
+
+Coordinates in MapLibre, Turf, and GeoJSON are `[longitude, latitude]`.
+
+```ts
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+```
+
+## Prerequisites
+
+Install MapLibre and Turf with the project's package manager.
+
+```bash
+npm i maplibre-gl @turf/turf
+```
+
+```bash
+bun i maplibre-gl @turf/turf
+```
+
+```bash
+yarn add maplibre-gl @turf/turf
+```
+
+```bash
+pnpm i maplibre-gl @turf/turf
+```
+
+Import the MapLibre CSS once in the component or an app-level stylesheet:
+
+```ts
+import 'maplibre-gl/dist/maplibre-gl.css';
+```
+
+## Basic map example
+
+```tsx
+import {useEffect, useRef, useState} from 'react';
+import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
+import maplibregl from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+
+export const MyComposition = () => {
+	const containerRef = useRef<HTMLDivElement>(null);
+	const {delayRender, continueRender} = useDelayRender();
+	const {width, height} = useVideoConfig();
+	const [loadingHandle] = useState(() => delayRender('Loading map'));
+
+	useEffect(() => {
+		if (!containerRef.current) {
+			return;
+		}
+
+		const mapInstance = new maplibregl.Map({
+			container: containerRef.current,
+			style: 'https://demotiles.maplibre.org/style.json',
+			center: zurich,
+			zoom: 7,
+			interactive: false,
+			attributionControl: false,
+			fadeDuration: 0,
+			canvasContextAttributes: {
+				preserveDrawingBuffer: true,
+			},
+		});
+
+		mapInstance.on('load', () => {
+			mapInstance.jumpTo({center: zurich, zoom: 7});
+			mapInstance.once('idle', () => {
+				continueRender(loadingHandle);
+			});
+		});
+	}, [continueRender, loadingHandle]);
+
+	return (
+		<AbsoluteFill>
+			<div ref={containerRef} style={{width, height, position: 'absolute'}} />
+		</AbsoluteFill>
+	);
+};
+```
+
+Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.
+
+## Animated flight route example
+
+This example shows the recommended pattern for route animations:
+
+- Turf creates the route and markers.
+- Turf slices the route for line reveal animation.
+- The camera has a separate route from the target route.
+- MapLibre's `calculateCameraOptionsFromTo()` is used for camera movement.
+- Frame 0 is prepared before `continueRender()`.
+
+```tsx
+import * as turf from '@turf/turf';
+import {useEffect, useRef, useState} from 'react';
+import {
+	AbsoluteFill,
+	Easing,
+	interpolate,
+	useCurrentFrame,
+	useDelayRender,
+	useVideoConfig,
+} from 'remotion';
+import maplibregl, {type GeoJSONSource, type Map} from 'maplibre-gl';
+import 'maplibre-gl/dist/maplibre-gl.css';
+
+const zurich: [number, number] = [8.5417, 47.3769];
+const newYork: [number, number] = [-74.006, 40.7128];
+
+const greatCircleLine = (from: [number, number], to: [number, number]) => {
+	const route = turf.greatCircle(from, to, {npoints: 100});
+
+	if (route.geometry.type === 'LineString') {
+		return turf.lineString(route.geometry.coordinates);
+	}
+
+	// Great-circle routes crossing the antimeridian can become MultiLineString.
+	// Keep the example valid by choosing the longest segment.
+	const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
+		return segment.length > longest.length ? segment : longest;
+	});
+
+	return turf.lineString(longestSegment);
+};
+
+const targetRoute = greatCircleLine(zurich, newYork);
+const targetRouteDistance = turf.length(targetRoute);
+
+const cameraRoute = greatCircleLine(zurich, newYork);
+const cameraRouteDistance = turf.length(cameraRoute);
+
+const cityMarkers = turf.featureCollection([
+	turf.point(zurich, {name: 'Zurich'}),
+	turf.point(newYork, {name: 'New York'}),
+]);
+
+const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));
+
+const distanceAlong = (totalDistance: number, progress: number) => {
+	// Keep the route non-empty at progress 0; Turf can error on zero-length slices.
+	return Math.max(0.001, totalDistance * clampProgress(progress));
+};
+
+const getPartialTargetRoute = (progress: number) => {
+	return turf.lineSliceAlong(
+		targetRoute,
+		0,
+		distanceAlong(targetRouteDistance, progress),
+	);
+};
+
+const getCameraOptions = (
+	map: Map,
+	progress: number,
+	cameraAltitudeMeters: number,
+	cameraLatitudeOffset: number,
+) => {
+	const target = turf.along(
+		targetRoute,
+		distanceAlong(targetRouteDistance, progress),
+	).geometry.coordinates;
+	const camera = turf.along(
+		cameraRoute,
+		distanceAlong(cameraRouteDistance, progress),
+	).geometry.coordinates;
+
+	return map.calculateCameraOptionsFromTo(
+		new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
+		cameraAltitudeMeters,
+		new maplibregl.LngLat(target[0], target[1]),
+	);
+};
+
+export const MyComposition = () => {
+	const containerRef = useRef<HTMLDivElement>(null);
+	const frame = useCurrentFrame();
+	const {delayRender, continueRender} = useDelayRender();
+	const {durationInFrames, height, width} = useVideoConfig();
+	const [map, setMap] = useState<Map | null>(null);
+	const [loadingHandle] = useState(() => delayRender('Loading MapLibre map'));
+
+	useEffect(() => {
+		if (!containerRef.current) {
+			return;
+		}
+
+		const mapInstance = new maplibregl.Map({
+			container: containerRef.current,
+			style: 'https://demotiles.maplibre.org/style.json',
+			center: zurich,
+			zoom: 7,
+			interactive: false,
+			attributionControl: false,
+			fadeDuration: 0,
+			canvasContextAttributes: {
+				preserveDrawingBuffer: true,
+			},
+		});
+
+		mapInstance.on('load', () => {
+			mapInstance.addSource('trace', {
+				type: 'geojson',
+				data: getPartialTargetRoute(0),
+			});
+
+			mapInstance.addLayer({
+				id: 'trace-line',
+				type: 'line',
+				source: 'trace',
+				layout: {
+					'line-cap': 'round',
+					'line-join': 'round',
+				},
+				paint: {
+					'line-color': '#111111',
+					'line-width': 7,
+				},
+			});
+
+			mapInstance.addSource('city-markers', {
+				type: 'geojson',
+				data: cityMarkers,
+			});
+
+			mapInstance.addLayer({
+				id: 'city-marker-dots',
+				type: 'circle',
+				source: 'city-markers',
+				paint: {
+					'circle-color': '#f03b20',
+					'circle-radius': 12,
+					'circle-stroke-color': '#ffffff',
+					'circle-stroke-width': 4,
+				},
+			});
+
+			mapInstance.addLayer({
+				id: 'city-marker-labels',
+				type: 'symbol',
+				source: 'city-markers',
+				layout: {
+					'text-allow-overlap': true,
+					'text-anchor': 'top',
+					'text-field': ['get', 'name'],
+					'text-offset': [0, 0.9],
+					'text-size': 28,
+				},
+				paint: {
+					'text-color': '#111111',
+					'text-halo-color': '#ffffff',
+					'text-halo-width': 3,
+				},
+			});
+
+			mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
+			mapInstance.once('idle', () => {
+				setMap(mapInstance);
+				continueRender(loadingHandle);
+			});
+		});
+	}, [continueRender, loadingHandle]);
+
+	useEffect(() => {
+		if (!map) {
+			return;
+		}
+
+		const handle = delayRender('Rendering MapLibre frame');
+		const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
+			extrapolateLeft: 'clamp',
+			extrapolateRight: 'clamp',
+		});
+		const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
+			extrapolateLeft: 'clamp',
+			extrapolateRight: 'clamp',
+			easing: Easing.inOut(Easing.cubic),
+		});
+		const cameraAltitudeMeters = interpolate(
+			timelineProgress,
+			[0, 0.28, 0.74, 1],
+			[180000, 2200000, 2200000, 180000],
+			{
+				extrapolateLeft: 'clamp',
+				extrapolateRight: 'clamp',
+				easing: Easing.inOut(Easing.cubic),
+			},
+		);
+		const cameraLatitudeOffset = interpolate(
+			timelineProgress,
+			[0, 0.28, 0.74, 1],
+			[1.1, 8, 8, 1.1],
+			{
+				extrapolateLeft: 'clamp',
+				extrapolateRight: 'clamp',
+				easing: Easing.inOut(Easing.cubic),
+			},
+		);
+		const trace = map.getSource('trace') as GeoJSONSource | undefined;
+
+		trace?.setData(getPartialTargetRoute(travelProgress));
+		map.jumpTo(
+			getCameraOptions(
+				map,
+				travelProgress,
+				cameraAltitudeMeters,
+				cameraLatitudeOffset,
+			),
+		);
+
+		map.once('idle', () => continueRender(handle));
+		// Force an idle event even if the camera parameters are unchanged from the previous frame.
+		map.triggerRepaint();
+	}, [continueRender, delayRender, durationInFrames, frame, map]);
+
+	return (
+		<AbsoluteFill style={{backgroundColor: '#e8eef3'}}>
+			<div ref={containerRef} style={{height, position: 'absolute', width}} />
+		</AbsoluteFill>
+	);
+};
+```
+
+## Camera guidance
+
+Use MapLibre's camera helper for camera movement:
+
+```ts
+map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);
+```
+
+A good pattern is to keep two concepts separate:
+
+- `targetRoute`: where the animated line is and where the camera looks.
+- `cameraRoute`: where the camera moves.
+
+Then use Turf to read positions from both routes for the same progress value:
+
+```ts
+const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
+const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;
+
+map.jumpTo(
+	map.calculateCameraOptionsFromTo(
+		new maplibregl.LngLat(camera[0], camera[1]),
+		cameraAltitudeMeters,
+		new maplibregl.LngLat(target[0], target[1]),
+	),
+);
+```
+
+For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.
+
+## Lines
+
+Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.
+
+For geodesic flight routes, use Turf:
+
+```ts
+const line = greatCircleLine(start, end);
+const distance = turf.length(line);
+const partialLine = turf.lineSliceAlong(
+	line,
+	0,
+	// Keep the route non-empty at progress 0.
+	Math.max(0.001, distance * progress),
+);
+```
+
+For a visually straight line on the map, use a simple GeoJSON `LineString` between the two points instead of `greatCircle()`.
+
+## Markers and labels
+
+Use map-native GeoJSON layers for markers and labels:
+
+```tsx
+mapInstance.addSource('markers', {
+	type: 'geojson',
+	data: turf.featureCollection([
+		turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
+	]),
+});
+
+mapInstance.addLayer({
+	id: 'marker-dots',
+	type: 'circle',
+	source: 'markers',
+	paint: {
+		'circle-color': '#f03b20',
+		'circle-radius': 12,
+		'circle-stroke-color': '#ffffff',
+		'circle-stroke-width': 4,
+	},
+});
+
+mapInstance.addLayer({
+	id: 'marker-labels',
+	type: 'symbol',
+	source: 'markers',
+	layout: {
+		'text-allow-overlap': true,
+		'text-anchor': 'top',
+		'text-field': ['get', 'name'],
+		'text-offset': [0, 0.9],
+		'text-size': 28,
+	},
+	paint: {
+		'text-color': '#111111',
+		'text-halo-color': '#ffffff',
+		'text-halo-width': 3,
+	},
+});
+```
+
+Make marker sizes and label font sizes large enough for the composition resolution.
+
+## Styles
+
+Default to the stock MapLibre demo style:
+
+```ts
+style: 'https://demotiles.maplibre.org/style.json'
+```
+
+If the user requests another style, use any valid MapLibre style JSON URL.
+
+## Rendering
+
+For WebGL map renders, prefer single concurrency and ANGLE:
+
+```bash
+bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1
+```
+
+Use the equivalent package runner for the project. In npm projects, use `npx`; in Bun projects, use `bunx`.
diff --git a/skills/remotion-best-practices/rules/measuring-dom-nodes.md b/skills/remotion-best-practices/rules/measuring-dom-nodes.md
new file mode 100644
index 00000000..4e63424f
--- /dev/null
+++ b/skills/remotion-best-practices/rules/measuring-dom-nodes.md
@@ -0,0 +1,34 @@
+---
+name: measuring-dom-nodes
+description: Measuring DOM element dimensions in Remotion
+metadata:
+  tags: measure, layout, dimensions, getBoundingClientRect, scale
+---
+
+# Measuring DOM nodes in Remotion
+
+Remotion applies a `scale()` transform to the video container, which affects values from `getBoundingClientRect()`. Use `useCurrentScale()` to get correct measurements.
+
+## Measuring element dimensions
+
+```tsx
+import { useCurrentScale } from "remotion";
+import { useRef, useEffect, useState } from "react";
+
+export const MyComponent = () => {
+  const ref = useRef<HTMLDivElement>(null);
+  const scale = useCurrentScale();
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    if (!ref.current) return;
+    const rect = ref.current.getBoundingClientRect();
+    setDimensions({
+      width: rect.width / scale,
+      height: rect.height / scale,
+    });
+  }, [scale]);
+
+  return <div ref={ref}>Content to measure</div>;
+};
+```
diff --git a/skills/remotion-best-practices/rules/measuring-text.md b/skills/remotion-best-practices/rules/measuring-text.md
new file mode 100644
index 00000000..070a184b
--- /dev/null
+++ b/skills/remotion-best-practices/rules/measuring-text.md
@@ -0,0 +1,140 @@
+---
+name: measuring-text
+description: Measuring text dimensions, fitting text to containers, and checking overflow
+metadata:
+  tags: measure, text, layout, dimensions, fitText, fillTextBox
+---
+
+# Measuring text in Remotion
+
+## Prerequisites
+
+Install @remotion/layout-utils if it is not already installed:
+
+```bash
+npx remotion add @remotion/layout-utils
+```
+
+## Measuring text dimensions
+
+Use `measureText()` to calculate the width and height of text:
+
+```tsx
+import { measureText } from "@remotion/layout-utils";
+
+const { width, height } = measureText({
+  text: "Hello World",
+  fontFamily: "Arial",
+  fontSize: 32,
+  fontWeight: "bold",
+});
+```
+
+Results are cached - duplicate calls return the cached result.
+
+## Fitting text to a width
+
+Use `fitText()` to find the optimal font size for a container:
+
+```tsx
+import { fitText } from "@remotion/layout-utils";
+
+const { fontSize } = fitText({
+  text: "Hello World",
+  withinWidth: 600,
+  fontFamily: "Inter",
+  fontWeight: "bold",
+});
+
+return (
+  <div
+    style={{
+      fontSize: Math.min(fontSize, 80), // Cap at 80px
+      fontFamily: "Inter",
+      fontWeight: "bold",
+    }}
+  >
+    Hello World
+  </div>
+);
+```
+
+## Checking text overflow
+
+Use `fillTextBox()` to check if text exceeds a box:
+
+```tsx
+import { fillTextBox } from "@remotion/layout-utils";
+
+const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });
+
+const words = ["Hello", "World", "This", "is", "a", "test"];
+for (const word of words) {
+  const { exceedsBox } = box.add({
+    text: word + " ",
+    fontFamily: "Arial",
+    fontSize: 24,
+  });
+  if (exceedsBox) {
+    // Text would overflow, handle accordingly
+    break;
+  }
+}
+```
+
+## Best practices
+
+**Load fonts first:** Only call measurement functions after fonts are loaded.
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+
+const { fontFamily, waitUntilDone } = loadFont("normal", {
+  weights: ["400"],
+  subsets: ["latin"],
+});
+
+waitUntilDone().then(() => {
+  // Now safe to measure
+  const { width } = measureText({
+    text: "Hello",
+    fontFamily,
+    fontSize: 32,
+  });
+});
+```
+
+**Use validateFontIsLoaded:** Catch font loading issues early:
+
+```tsx
+measureText({
+  text: "Hello",
+  fontFamily: "MyCustomFont",
+  fontSize: 32,
+  validateFontIsLoaded: true, // Throws if font not loaded
+});
+```
+
+**Match font properties:** Use the same properties for measurement and rendering:
+
+```tsx
+const fontStyle = {
+  fontFamily: "Inter",
+  fontSize: 32,
+  fontWeight: "bold" as const,
+  letterSpacing: "0.5px",
+};
+
+const { width } = measureText({
+  text: "Hello",
+  ...fontStyle,
+});
+
+return <div style={fontStyle}>Hello</div>;
+```
+
+**Avoid padding and border:** Use `outline` instead of `border` to prevent layout differences:
+
+```tsx
+<div style={{ outline: "2px solid red" }}>Text</div>
+```
diff --git a/skills/remotion-best-practices/rules/parameters.md b/skills/remotion-best-practices/rules/parameters.md
new file mode 100644
index 00000000..88608006
--- /dev/null
+++ b/skills/remotion-best-practices/rules/parameters.md
@@ -0,0 +1,109 @@
+---
+name: parameters
+description: Make a video parametrizable by adding a Zod schema
+metadata:
+  tags: parameters, zod, schema
+---
+
+To make a video parametrizable, a Zod schema can be added to a composition.
+
+First, `zod` must be installed .
+
+Search the project for lockfiles and run the correct command depending on the package manager:
+
+If `package-lock.json` is found, use the following command:
+
+```bash
+npm i zod
+```
+
+If `bun.lockb` is found, use the following command:
+
+```bash
+bun i zod
+```
+
+If `yarn.lock` is found, use the following command:
+
+```bash
+yarn add zod
+```
+
+If `pnpm-lock.yaml` is found, use the following command:
+
+```bash
+pnpm i zod
+```
+
+Then, a Zod schema can be defined alongside the component:
+
+```tsx title="src/MyComposition.tsx"
+import { z } from "zod";
+
+export const MyCompositionSchema = z.object({
+  title: z.string(),
+});
+
+const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => {
+  return (
+    <div>
+      <h1>{props.title}</h1>
+    </div>
+  );
+};
+```
+
+In the root file, the schema can be passed to the composition:
+
+```tsx title="src/Root.tsx"
+import { Composition } from "remotion";
+import { MycComponent, MyCompositionSchema } from "./MyComposition";
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id="MyComposition"
+      component={MyComponent}
+      durationInFrames={100}
+      fps={30}
+      width={1080}
+      height={1080}
+      defaultProps={{ title: "Hello World" }}
+      schema={MyCompositionSchema}
+    />
+  );
+};
+```
+
+Now, the user can edit the parameter visually in the sidebar.
+
+All schemas that are supported by Zod are supported by Remotion.
+
+Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.
+
+## Color picker
+
+For adding a color picker, use `zColor()` from `@remotion/zod-types`.
+
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/zod-types # If project uses npm
+bunx remotion add @remotion/zod-types # If project uses bun
+yarn remotion add @remotion/zod-types # If project uses yarn
+pnpm exec remotion add @remotion/zod-types # If project uses pnpm
+```
+
+Then import `zColor` from `@remotion/zod-types`:
+
+```tsx
+import { zColor } from "@remotion/zod-types";
+```
+
+Then use it in the schema:
+
+```tsx
+export const MyCompositionSchema = z.object({
+  color: zColor(),
+});
+```
diff --git a/skills/remotion-best-practices/rules/sequencing.md b/skills/remotion-best-practices/rules/sequencing.md
new file mode 100644
index 00000000..a2af6690
--- /dev/null
+++ b/skills/remotion-best-practices/rules/sequencing.md
@@ -0,0 +1,144 @@
+---
+name: sequencing
+description: Sequencing patterns for Remotion - delay, trim, limit duration of items
+metadata:
+  tags: sequence, series, timing, delay, trim
+---
+
+Use `<Sequence>` to delay when an element appears in the timeline.
+
+```tsx
+import { Sequence } from "remotion";
+
+export const Title = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: "clamp",
+    extrapolateLeft: "clamp",
+    easing: Easing.bezier(0.16, 1, 0.3, 1),
+  });
+
+  return <div style={{ opacity }}>Title</div>;
+};
+
+export const Subtitle = () => {
+  return <div>Subtitle</div>;
+};
+
+const Main = () => {
+  const {fps} = useVideoConfig();
+
+  return (
+    <AbsoluteFill>
+      <Sequence>
+        <Background />
+      </Sequence>
+      <Sequence from={1 * fps} durationInFrames={2 * fps} layout="none">
+        <Title />
+      </Sequence>
+      <Sequence from={2 * fps} durationInFrames={2 * fps} layout="none">
+        <Subtitle />
+      </Sequence>
+    </AbsoluteFill>
+  );
+}
+```
+
+This will by default wrap the component in an absolute fill element.  
+If the items should not be wrapped, use the `layout` prop:
+
+```tsx
+<Sequence layout="none">
+  <Title />
+</Sequence>
+```
+
+## Premounting
+
+This loads the component in the timeline before it is actually played.  
+Always premount any `<Sequence>`!
+
+```tsx
+<Sequence premountFor={1 * fps}>
+  <Title />
+</Sequence>
+```
+
+## Series
+
+Use `<Series>` when elements should play one after another without overlap.
+
+```tsx
+import { Series } from "remotion";
+
+<Series>
+  <Series.Sequence durationInFrames={45}>
+    <Intro />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={60}>
+    <MainContent />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={30}>
+    <Outro />
+  </Series.Sequence>
+</Series>;
+```
+
+Same as with `<Sequence>`, the items will be wrapped in an absolute fill element by default when using `<Series.Sequence>`, unless the `layout` prop is set to `none`.
+
+### Series with overlaps
+
+Use negative offset for overlapping sequences:
+
+```tsx
+<Series>
+  <Series.Sequence durationInFrames={60}>
+    <SceneA />
+  </Series.Sequence>
+  <Series.Sequence offset={-15} durationInFrames={60}>
+    {/* Starts 15 frames before SceneA ends */}
+    <SceneB />
+  </Series.Sequence>
+</Series>
+```
+
+## Frame References Inside Sequences
+
+Inside a Sequence, `useCurrentFrame()` returns the local frame (starting from 0):
+
+```tsx
+<Sequence from={60} durationInFrames={30}>
+  <MyComponent />
+  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
+</Sequence>
+```
+
+## Nested Sequences
+
+Sequences can be nested for complex timing:
+
+```tsx
+<Sequence from={0} durationInFrames={120}>
+  <Background />
+  <Sequence from={15} durationInFrames={90} layout="none">
+    <Title />
+  </Sequence>
+  <Sequence from={45} durationInFrames={60} layout="none">
+    <Subtitle />
+  </Sequence>
+</Sequence>
+```
+
+## Nesting compositions within another
+
+To add a composition within another composition, you can use the `<Sequence>` component with a `width` and `height` prop to specify the size of the composition.
+
+```tsx
+<AbsoluteFill>
+  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
+    <CompositionComponent />
+  </Sequence>
+</AbsoluteFill>
+```
diff --git a/skills/remotion-best-practices/rules/sfx.md b/skills/remotion-best-practices/rules/sfx.md
new file mode 100644
index 00000000..41fdc500
--- /dev/null
+++ b/skills/remotion-best-practices/rules/sfx.md
@@ -0,0 +1,30 @@
+---
+name: sfx
+description: Including sound effects
+metadata:
+  tags: sfx, sound, effect, audio
+---
+
+To include a sound effect, use the `<Audio>` tag:
+
+```tsx
+import { Audio } from "@remotion/sfx";
+
+<Audio src={"https://remotion.media/whoosh.wav"} />;
+```
+
+The following sound effects are available:
+
+- `https://remotion.media/whoosh.wav`
+- `https://remotion.media/whip.wav`
+- `https://remotion.media/page-turn.wav`
+- `https://remotion.media/switch.wav`
+- `https://remotion.media/mouse-click.wav`
+- `https://remotion.media/shutter-modern.wav`
+- `https://remotion.media/shutter-old.wav`
+- `https://remotion.media/ding.wav`
+- `https://remotion.media/bruh.wav`
+- `https://remotion.media/vine-boom.wav`
+- `https://remotion.media/windows-xp-error.wav`
+
+For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.
diff --git a/skills/remotion-best-practices/rules/silence-detection.md b/skills/remotion-best-practices/rules/silence-detection.md
new file mode 100644
index 00000000..33d20988
--- /dev/null
+++ b/skills/remotion-best-practices/rules/silence-detection.md
@@ -0,0 +1,71 @@
+---
+name: silence-detection
+description: Adaptive silence detection for video/audio files using FFmpeg loudnorm and silencedetect
+metadata:
+  tags: silence, detection, trimming, ffmpeg, loudnorm, audio
+---
+
+# Adaptive Silence Detection
+
+Detect silent segments in video or audio files.
+
+Requires FFmpeg — see [ffmpeg.md](./ffmpeg.md) for how to invoke it in Remotion projects.
+
+## Step 1: Measure loudness with `loudnorm`
+
+Use the `loudnorm` filter in JSON mode to get the EBU R128 integrated loudness and gating threshold for each file:
+
+```bash
+npx remotion ffmpeg -i public/video.mov -map 0:a -af loudnorm=print_format=json -f null /dev/null
+```
+
+As output you will get:
+- `input_i`: Integrated loudness (dB) — the overall perceived volume
+- `input_thresh`: EBU R128 gating threshold (dB) — the level below which audio is considered too quiet to count toward loudness measurement
+
+## Step 2: Detect silences using adaptive threshold
+
+Pass the `input_thresh` value from step 1 as the `noise` parameter to `silencedetect`:
+
+```bash
+npx remotion ffmpeg -i public/video.mov -map 0:a -af "silencedetect=noise=${THRESH}dB:d=0.5" -f null /dev/null
+```
+
+Parameters:
+- `noise`: The threshold below which audio is considered silent. Use `input_thresh` from step 1.
+- `d`: Minimum silence duration in seconds. `0.5` is a good default.
+
+## Interpreting the output
+
+The filter outputs pairs of `silence_start` and `silence_end` timestamps:
+
+```
+[silencedetect] silence_start: 0
+[silencedetect] silence_end: 2.241021 | silence_duration: 2.241021
+[silencedetect] silence_start: 38.77425
+[silencedetect] silence_end: 39.619604 | silence_duration: 0.845354
+```
+
+## Identifying leading and trailing silence
+
+- **Leading silence**: Consecutive silence segments starting at or near 0. If the first `silence_start` is > 0.5s, there is no leading silence.
+- **Trailing silence**: The last silence segment that extends to (or near) the end of the file. Compare the last `silence_end` with the file's total duration.
+
+When multiple silences are nearly contiguous at the start or end (gap < 0.2s), treat them as a single leading/trailing silence block.
+
+## Using with Remotion's `<Video>` component
+
+Apply the detected trim points using `trimBefore` and `trimAfter` (values are in frames):
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile, useVideoConfig } from "remotion";
+
+const { fps } = useVideoConfig();
+
+<Video
+  src={staticFile("video.mov")}
+  trimBefore={Math.floor(leadingEnd * fps)}
+  trimAfter={Math.ceil(trailingStart * fps)}
+/>
+```
diff --git a/skills/remotion-best-practices/rules/subtitles.md b/skills/remotion-best-practices/rules/subtitles.md
new file mode 100644
index 00000000..2291eef3
--- /dev/null
+++ b/skills/remotion-best-practices/rules/subtitles.md
@@ -0,0 +1,36 @@
+---
+name: subtitles
+description: subtitles and caption rules
+metadata:
+  tags: subtitles, captions, remotion, json
+---
+
+All captions must be processed in JSON. The captions must use the `Caption` type which is the following:
+
+```ts
+import type { Caption } from "@remotion/captions";
+```
+
+This is the definition:
+
+```ts
+type Caption = {
+  text: string;
+  startMs: number;
+  endMs: number;
+  timestampMs: number | null;
+  confidence: number | null;
+};
+```
+
+## Generating captions
+
+To transcribe video and audio files to generate captions, load the [./transcribe-captions.md](./transcribe-captions.md) file for more instructions.
+
+## Displaying captions
+
+To display captions in your video, load the [./display-captions.md](./display-captions.md) file for more instructions.
+
+## Importing captions
+
+To import captions from a .srt file, load the [./import-srt-captions.md](./import-srt-captions.md) file for more instructions.
diff --git a/skills/remotion-best-practices/rules/tailwind.md b/skills/remotion-best-practices/rules/tailwind.md
new file mode 100644
index 00000000..928f6331
--- /dev/null
+++ b/skills/remotion-best-practices/rules/tailwind.md
@@ -0,0 +1,11 @@
+---
+name: tailwind
+description: Using TailwindCSS in Remotion.
+metadata:
+---
+
+You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.
+
+Don't use `transition-*` or `animate-*` classes - always animate using the `useCurrentFrame()` hook.
+
+Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.
diff --git a/skills/remotion-best-practices/rules/text-animations.md b/skills/remotion-best-practices/rules/text-animations.md
new file mode 100644
index 00000000..e38b1c57
--- /dev/null
+++ b/skills/remotion-best-practices/rules/text-animations.md
@@ -0,0 +1,20 @@
+---
+name: text-animations
+description: Typography and text animation patterns for Remotion.
+metadata:
+  tags: typography, text, typewriter, highlighter ken
+---
+
+## Text animations
+
+Based on `useCurrentFrame()`, reduce the string character by character to create a typewriter effect.
+
+## Typewriter Effect
+
+See [Typewriter](assets/text-animations-typewriter.tsx) for an advanced example with a blinking cursor and a pause after the first sentence.
+
+Always use string slicing for typewriter effects. Never use per-character opacity.
+
+## Word Highlighting
+
+See [Word Highlight](assets/text-animations-word-highlight.tsx) for an example for how a word highlight is animated, like with a highlighter pen.
diff --git a/skills/remotion-best-practices/rules/timing.md b/skills/remotion-best-practices/rules/timing.md
new file mode 100644
index 00000000..b4a32312
--- /dev/null
+++ b/skills/remotion-best-practices/rules/timing.md
@@ -0,0 +1,136 @@
+---
+name: timing
+description: Interpolation and timing in Remotion—prefer interpolate with Bézier easing; springs as a specialized option
+metadata:
+  tags: easing, bezier, interpolation, spring, timing
+---
+
+Drive motion with `interpolate()` over explicit frame range. To customize timing, use **`Easing.bezier`**. The four parameters are the same as CSS `cubic-bezier(x1, y1, x2, y2)`.
+
+A simple linear interpolation is done using the `interpolate` function.
+
+```ts title="Going from 0 to 1 over 100 frames"
+import { interpolate } from "remotion";
+
+const opacity = interpolate(frame, [0, 100], [0, 1]);
+```
+
+By default, the values are not clamped, so the value can go outside the range [0, 1].  
+Here is how they can be clamped:
+
+```ts title="Going from 0 to 1 over 100 frames with extrapolation"
+const opacity = interpolate(frame, [0, 100], [0, 1], {
+  extrapolateRight: "clamp",
+  extrapolateLeft: "clamp",
+});
+```
+
+## Bézier easing
+
+Use `Easing.bezier(x1, y1, x2, y2)` inside the `interpolate` options object. The curve is identical in spirit to CSS animations and transitions, which helps when you are stealing timing from the web or from a designer’s spec.
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const opacity = interpolate(frame, [0, 60], [0, 1], {
+  easing: Easing.bezier(0.16, 1, 0.3, 1),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+### Examples (copy-paste curves)
+
+**1. Crisp UI entrance (strong ease-out, no overshoot)** — slows nicely into the rest value; similar to many system “deceleration” curves.
+
+```tsx
+const enter = interpolate(frame, [0, 45], [0, 1], {
+  easing: Easing.bezier(0.16, 1, 0.3, 1),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+**2. Editorial / slow fade (balanced ease-in-out)** — symmetric acceleration and deceleration over a hold-friendly move.
+
+```tsx
+const progress = interpolate(frame, [0, 90], [0, 1], {
+  easing: Easing.bezier(0.45, 0, 0.55, 1),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+**3. Playful overshoot (control point y > 1)** — a little past the target then settles; use sparingly for emphasis.
+
+```tsx
+const pop = interpolate(frame, [0, 30], [0, 1], {
+  easing: Easing.bezier(0.34, 1.56, 0.64, 1),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+## Preset easings (`Easing.in` / `Easing.out` / named curves)
+
+Easing can be added to the `interpolate` function without a custom cubic:
+
+```ts
+import { interpolate, Easing } from "remotion";
+
+const value1 = interpolate(frame, [0, 100], [0, 1], {
+  easing: Easing.inOut(Easing.cubic),
+  extrapolateLeft: "clamp",
+  extrapolateRight: "clamp",
+});
+```
+
+The default easing is `Easing.linear`.  
+Convexities:
+
+- `Easing.in` — starting slow and accelerating
+- `Easing.out` — starting fast and slowing down
+- `Easing.inOut`
+
+Named curves (from most linear to most curved):
+
+- `Easing.quad`
+- `Easing.cubic` (good default when you do not need a custom cubic)
+- `Easing.sin`
+- `Easing.exp`
+- `Easing.circle`
+
+### Easing direction for enter/exit animations
+
+Use `Easing.out` for enter animations (starts fast, decelerates into place) and `Easing.in` for exit animations (starts slow, accelerates away). This feels natural because elements arrive with momentum and leave with gravity. When you need a specific curve from design, prefer a single `Easing.bezier(...)` instead of stacking presets.
+
+## Composing interpolations
+
+When multiple properties share the same timing (e.g. a slide-in panel and a video shift), avoid duplicating the full interpolation for each property. Instead, create a single normalized progress value (0 to 1) and derive each property from it:
+
+```tsx
+const slideIn = interpolate(
+  frame,
+  [slideInStart, slideInStart + slideInDuration],
+  [0, 1],
+  {
+    easing: Easing.bezier(0.22, 1, 0.36, 1),
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  },
+);
+const slideOut = interpolate(
+  frame,
+  [slideOutStart, slideOutStart + slideOutDuration],
+  [0, 1],
+  { easing: Easing.in(Easing.cubic), extrapolateLeft: "clamp", extrapolateRight: "clamp" },
+);
+const progress = slideIn - slideOut;
+
+// Derive multiple properties from the same progress
+const overlayX = interpolate(progress, [0, 1], [100, 0]);
+const videoX = interpolate(progress, [0, 1], [0, -20]);
+const opacity = interpolate(progress, [0, 1], [0, 1]);
+```
+
+The key idea: separate **timing** (when and how fast) from **mapping** (what values to animate between).
diff --git a/skills/remotion-best-practices/rules/transcribe-captions.md b/skills/remotion-best-practices/rules/transcribe-captions.md
new file mode 100644
index 00000000..ba649d57
--- /dev/null
+++ b/skills/remotion-best-practices/rules/transcribe-captions.md
@@ -0,0 +1,70 @@
+---
+name: transcribe-captions
+description: Transcribing audio to generate captions in Remotion
+metadata:
+  tags: captions, transcribe, whisper, audio, speech-to-text
+---
+
+# Transcribing audio
+
+To transcribe audio to generate captions in Remotion, you can use the [`transcribe()`](https://www.remotion.dev/docs/install-whisper-cpp/transcribe) function from the [`@remotion/install-whisper-cpp`](https://www.remotion.dev/docs/install-whisper-cpp) package.
+
+## Prerequisites
+
+First, the @remotion/install-whisper-cpp package needs to be installed.
+If it is not installed, use the following command:
+
+```bash
+npx remotion add @remotion/install-whisper-cpp
+```
+
+## Transcribing
+
+Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.
+
+```ts
+import path from "path";
+import {
+  downloadWhisperModel,
+  installWhisperCpp,
+  transcribe,
+  toCaptions,
+} from "@remotion/install-whisper-cpp";
+import fs from "fs";
+
+const to = path.join(process.cwd(), "whisper.cpp");
+
+await installWhisperCpp({
+  to,
+  version: "1.5.5",
+});
+
+await downloadWhisperModel({
+  model: "medium.en",
+  folder: to,
+});
+
+// Convert the audio to a 16KHz wav file first if needed:
+// import {execSync} from 'child_process';
+// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');
+
+const whisperCppOutput = await transcribe({
+  model: "medium.en",
+  whisperPath: to,
+  whisperCppVersion: "1.5.5",
+  inputPath: "/path/to/audio123.wav",
+  tokenLevelTimestamps: true,
+});
+
+// Optional: Apply our recommended postprocessing
+const { captions } = toCaptions({
+  whisperCppOutput,
+});
+
+// Write it to the public/ folder so it can be fetched from Remotion
+fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));
+```
+
+Transcribe each clip individually and create multiple JSON files.
+
+See [Displaying captions](display-captions.md) for how to display the captions in Remotion.
diff --git a/skills/remotion-best-practices/rules/transitions.md b/skills/remotion-best-practices/rules/transitions.md
new file mode 100644
index 00000000..91ef8bd8
--- /dev/null
+++ b/skills/remotion-best-practices/rules/transitions.md
@@ -0,0 +1,197 @@
+---
+name: transitions
+description: Scene transitions and overlays for Remotion using TransitionSeries.
+metadata:
+  tags: transitions, overlays, fade, slide, wipe, scenes
+---
+
+## TransitionSeries
+
+`<TransitionSeries>` arranges scenes and supports two ways to enhance the cut point between them:
+
+- **Transitions** (`<TransitionSeries.Transition>`) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
+- **Overlays** (`<TransitionSeries.Overlay>`) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.
+
+Children are absolutely positioned.
+
+## Prerequisites
+
+```bash
+npx remotion add @remotion/transitions
+```
+
+## Transition example
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Overlay example
+
+Any React component can be used as an overlay. For a ready-made effect, see the **light-leaks** rule.
+
+```tsx
+import { TransitionSeries } from "@remotion/transitions";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={20}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Mixing transitions and overlays
+
+Transitions and overlays can coexist in the same `<TransitionSeries>`, but an overlay cannot be adjacent to a transition or another overlay.
+
+```tsx
+import { TransitionSeries, linearTiming } from "@remotion/transitions";
+import { fade } from "@remotion/transitions/fade";
+import { LightLeak } from "@remotion/light-leaks";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Overlay durationInFrames={30}>
+    <LightLeak />
+  </TransitionSeries.Overlay>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneC />
+  </TransitionSeries.Sequence>
+</TransitionSeries>;
+```
+
+## Transition props
+
+`<TransitionSeries.Transition>` requires:
+
+- `presentation` — the visual effect (e.g. `fade()`, `slide()`, `wipe()`).
+- `timing` — controls speed and easing (e.g. `linearTiming()`, `springTiming()`).
+
+## Overlay props
+
+`<TransitionSeries.Overlay>` accepts:
+
+- `durationInFrames` — how long the overlay is visible (positive integer).
+- `offset?` — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: `0`.
+
+## Available transition types
+
+Import transitions from their respective modules:
+
+```tsx
+import { fade } from "@remotion/transitions/fade";
+import { slide } from "@remotion/transitions/slide";
+import { wipe } from "@remotion/transitions/wipe";
+import { flip } from "@remotion/transitions/flip";
+import { clockWipe } from "@remotion/transitions/clock-wipe";
+```
+
+## Slide transition with direction
+
+```tsx
+import { slide } from "@remotion/transitions/slide";
+
+<TransitionSeries.Transition
+  presentation={slide({ direction: "from-left" })}
+  timing={linearTiming({ durationInFrames: 20 })}
+/>;
+```
+
+Directions: `"from-left"`, `"from-right"`, `"from-top"`, `"from-bottom"`
+
+## Timing options
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+// Linear timing - constant speed
+linearTiming({ durationInFrames: 20 });
+
+// Spring timing - organic motion
+springTiming({ config: { damping: 200 }, durationInFrames: 25 });
+```
+
+## Duration calculation
+
+Transitions overlap adjacent scenes, so the total composition length is **shorter** than the sum of all sequence durations. Overlays do **not** affect the total duration.
+
+For example, with two 60-frame sequences and a 15-frame transition:
+
+- Without transitions: `60 + 60 = 120` frames
+- With transition: `60 + 60 - 15 = 105` frames
+
+Adding an overlay between two other sequences does not change the total.
+
+### Getting the duration of a transition
+
+Use the `getDurationInFrames()` method on the timing object:
+
+```tsx
+import { linearTiming, springTiming } from "@remotion/transitions";
+
+const linearDuration = linearTiming({
+  durationInFrames: 20,
+}).getDurationInFrames({ fps: 30 });
+// Returns 20
+
+const springDuration = springTiming({
+  config: { damping: 200 },
+}).getDurationInFrames({ fps: 30 });
+// Returns calculated duration based on spring physics
+```
+
+For `springTiming` without an explicit `durationInFrames`, the duration depends on `fps` because it calculates when the spring animation settles.
+
+### Calculating total composition duration
+
+```tsx
+import { linearTiming } from "@remotion/transitions";
+
+const scene1Duration = 60;
+const scene2Duration = 60;
+const scene3Duration = 60;
+
+const timing1 = linearTiming({ durationInFrames: 15 });
+const timing2 = linearTiming({ durationInFrames: 20 });
+
+const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
+const transition2Duration = timing2.getDurationInFrames({ fps: 30 });
+
+const totalDuration =
+  scene1Duration +
+  scene2Duration +
+  scene3Duration -
+  transition1Duration -
+  transition2Duration;
+// 60 + 60 + 60 - 15 - 20 = 145 frames
+```
diff --git a/skills/remotion-best-practices/rules/transparent-videos.md b/skills/remotion-best-practices/rules/transparent-videos.md
new file mode 100644
index 00000000..dce5de50
--- /dev/null
+++ b/skills/remotion-best-practices/rules/transparent-videos.md
@@ -0,0 +1,106 @@
+---
+name: transparent-videos
+description: Rendering transparent videos in Remotion
+metadata:
+  tags: transparent, alpha, codec, vp9, prores, webm
+---
+
+# Rendering Transparent Videos
+
+Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.
+
+## Transparent ProRes
+
+Ideal for when importing into video editing software.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva444p10le");
+Config.setCodec("prores");
+Config.setProResProfile("4444");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "prores",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva444p10le",
+    defaultProResProfile: "4444",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
+
+## Transparent WebM (VP9)
+
+Ideal for when playing in a browser.
+
+**CLI:**
+
+```bash
+npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm
+```
+
+**Default in Studio** (restart Studio after changing):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp9");
+```
+
+**Setting it as the default export settings for a composition** (using `calculateMetadata`):
+
+```tsx
+import { CalculateMetadataFunction } from "remotion";
+
+const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  return {
+    defaultCodec: "vp8",
+    defaultVideoImageFormat: "png",
+    defaultPixelFormat: "yuva420p",
+  };
+};
+
+<Composition
+  id="my-video"
+  component={MyVideo}
+  durationInFrames={150}
+  fps={30}
+  width={1920}
+  height={1080}
+  calculateMetadata={calculateMetadata}
+/>;
+```
diff --git a/skills/remotion-best-practices/rules/trimming.md b/skills/remotion-best-practices/rules/trimming.md
new file mode 100644
index 00000000..e7534d1c
--- /dev/null
+++ b/skills/remotion-best-practices/rules/trimming.md
@@ -0,0 +1,51 @@
+---
+name: trimming
+description: Trimming patterns for Remotion - cut the beginning or end of animations
+metadata:
+  tags: sequence, trim, clip, cut, offset
+---
+
+Use `<Sequence>` with a negative `from` value to trim the start of an animation.
+
+## Trim the Beginning
+
+A negative `from` value shifts time backwards, making the animation start partway through:
+
+```tsx
+import { Sequence, useVideoConfig } from "remotion";
+
+const fps = useVideoConfig();
+
+<Sequence from={-0.5 * fps}>
+  <MyAnimation />
+</Sequence>;
+```
+
+The animation appears 15 frames into its progress - the first 15 frames are trimmed off.
+Inside `<MyAnimation>`, `useCurrentFrame()` starts at 15 instead of 0.
+
+## Trim the End
+
+Use `durationInFrames` to unmount content after a specified duration:
+
+```tsx
+<Sequence durationInFrames={1.5 * fps}>
+  <MyAnimation />
+</Sequence>
+```
+
+The animation plays for 45 frames, then the component unmounts.
+
+## Trim and Delay
+
+Nest sequences to both trim the beginning and delay when it appears:
+
+```tsx
+<Sequence from={30}>
+  <Sequence from={-15}>
+    <MyAnimation />
+  </Sequence>
+</Sequence>
+```
+
+The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.
diff --git a/skills/remotion-best-practices/rules/videos.md b/skills/remotion-best-practices/rules/videos.md
new file mode 100644
index 00000000..4d99b31e
--- /dev/null
+++ b/skills/remotion-best-practices/rules/videos.md
@@ -0,0 +1,171 @@
+---
+name: videos
+description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+metadata:
+  tags: video, media, trim, volume, speed, loop, pitch
+---
+
+# Using videos in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/media # If project uses npm
+bunx remotion add @remotion/media # If project uses bun
+yarn remotion add @remotion/media # If project uses yarn
+pnpm exec remotion add @remotion/media # If project uses pnpm
+```
+
+Use `<Video>` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+## Delaying
+
+Wrap the video in a `<Sequence>` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Video src={staticFile("video.mp4")} />
+  </Sequence>
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Video src={staticFile("video.mp4")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+<Video src={staticFile("video.mp4")} muted />
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
+<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the video indefinitely:
+
+```tsx
+<Video src={staticFile("video.mp4")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.
diff --git a/skills/remotion-best-practices/rules/voiceover.md b/skills/remotion-best-practices/rules/voiceover.md
new file mode 100644
index 00000000..d7b23504
--- /dev/null
+++ b/skills/remotion-best-practices/rules/voiceover.md
@@ -0,0 +1,99 @@
+---
+name: voiceover
+description: Adding AI-generated voiceover to Remotion compositions using TTS
+metadata:
+  tags: voiceover, audio, elevenlabs, tts, speech, calculateMetadata, dynamic duration
+---
+
+# Adding AI voiceover to a Remotion composition
+
+Use ElevenLabs TTS to generate speech audio per scene, then use [`calculateMetadata`](./calculate-metadata) to dynamically size the composition to match the audio.
+
+## Prerequisites
+
+By default this guide uses **ElevenLabs** as the TTS provider (`ELEVENLABS_API_KEY` environment variable). Users may substitute any TTS service that can produce an audio file.
+
+If the user has not specified a TTS provider, recommend ElevenLabs and ask for their API key.
+
+Ensure the environment variable is available when running the generation script:
+
+```bash
+node --strip-types generate-voiceover.ts
+```
+
+## Generating audio with ElevenLabs
+
+Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the `public/` directory so Remotion can access them via `staticFile()`.
+
+The core API call for a single scene:
+
+```ts title="generate-voiceover.ts"
+const response = await fetch(
+  `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`,
+  {
+    method: "POST",
+    headers: {
+      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
+      "Content-Type": "application/json",
+      Accept: "audio/mpeg",
+    },
+    body: JSON.stringify({
+      text: "Welcome to the show.",
+      model_id: "eleven_multilingual_v2",
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+      },
+    }),
+  },
+);
+
+const audioBuffer = Buffer.from(await response.arrayBuffer());
+writeFileSync(`public/voiceover/${compositionId}/${scene.id}.mp3`, audioBuffer);
+```
+
+## Dynamic composition duration with calculateMetadata
+
+Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.
+
+```tsx
+import { CalculateMetadataFunction, staticFile } from "remotion";
+import { getAudioDuration } from "./get-audio-duration";
+
+const FPS = 30;
+
+const SCENE_AUDIO_FILES = [
+  "voiceover/my-comp/scene-01-intro.mp3",
+  "voiceover/my-comp/scene-02-main.mp3",
+  "voiceover/my-comp/scene-03-outro.mp3",
+];
+
+export const calculateMetadata: CalculateMetadataFunction<Props> = async ({
+  props,
+}) => {
+  const durations = await Promise.all(
+    SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))),
+  );
+
+  const sceneDurations = durations.map((durationInSeconds) => {
+    return durationInSeconds * FPS;
+  });
+
+  return {
+    durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)),
+  };
+};
+```
+
+The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.
+
+If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)
+
+## Rendering audio in the component
+
+See [audio.md](./audio.md) for more information on how to render audio in the component.
+
+## Delaying audio start
+
+See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.
diff --git a/skills/tesla-api/SKILL.md b/skills/tesla-api/SKILL.md
index c18c13c5..92b6d8f0 100644
--- a/skills/tesla-api/SKILL.md
+++ b/skills/tesla-api/SKILL.md
@@ -35,7 +35,7 @@ This will:
 
 ### Environment variables:
 
-- `TESLA_EMAIL` — Your Tesla account email
+- `TESLA_EMAIL` - Your Tesla account email
 - Token cached in `~/.tesla_cache.json`
 
 ## Multi-Vehicle Support
@@ -120,7 +120,7 @@ https://tesla-api.timdorr.com
 - All communication is between your machine and Tesla's servers only
 
 **What this skill does NOT do:**
-- Does not store your Tesla password — uses OAuth token flow
+- Does not store your Tesla password - uses OAuth token flow
 - Does not send credentials or vehicle data to any third party
 - Does not access any system resources beyond the Tesla API
 - Cannot be invoked autonomously by the agent (`disable-model-invocation: true`)
@@ -130,4 +130,4 @@ https://tesla-api.timdorr.com
 - Refresh token cached in `~/.tesla_cache.json` with restricted permissions
 - Tokens auto-refresh for ~30 days
 - Only use on trusted, personal machines
-- Review `scripts/tesla.py` before first use — it communicates only with Tesla's official API
+- Review `scripts/tesla.py` before first use - it communicates only with Tesla's official API
diff --git a/skills/vercel-cli-with-tokens/SKILL.md b/skills/vercel-cli-with-tokens/SKILL.md
new file mode 100644
index 00000000..814423d0
--- /dev/null
+++ b/skills/vercel-cli-with-tokens/SKILL.md
@@ -0,0 +1,353 @@
+---
+name: vercel-cli-with-tokens
+description: Deploy and manage projects on Vercel using token-based authentication. Use when working with Vercel CLI using access tokens rather than interactive login — e.g. "deploy to vercel", "set up vercel", "add environment variables to vercel".
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel CLI with Tokens
+
+Deploy and manage projects on Vercel using the CLI with token-based authentication, without relying on `vercel login`.
+
+## Step 1: Locate the Vercel Token
+
+Before running any Vercel CLI commands, identify where the token is coming from. Work through these scenarios in order:
+
+### A) `VERCEL_TOKEN` is already set in the environment
+
+```bash
+printenv VERCEL_TOKEN
+```
+
+If this returns a value, you're ready. Skip to Step 2.
+
+### B) Token is in a `.env` file under `VERCEL_TOKEN`
+
+```bash
+grep '^VERCEL_TOKEN=' .env 2>/dev/null
+```
+
+If found, export it:
+
+```bash
+export VERCEL_TOKEN=$(grep '^VERCEL_TOKEN=' .env | cut -d= -f2-)
+```
+
+### C) Token is in a `.env` file under a different name
+
+Look for any variable that looks like a Vercel token (Vercel tokens typically start with `vca_`):
+
+```bash
+grep -i 'vercel' .env 2>/dev/null
+```
+
+Inspect the output to identify which variable holds the token, then export it as `VERCEL_TOKEN`:
+
+```bash
+export VERCEL_TOKEN=$(grep '^<VARIABLE_NAME>=' .env | cut -d= -f2-)
+```
+
+### D) No token found — ask the user
+
+If none of the above yield a token, ask the user to provide one. They can create a Vercel access token at vercel.com/account/tokens.
+
+---
+
+**Important:** Once `VERCEL_TOKEN` is exported as an environment variable, the Vercel CLI reads it natively — **do not pass it as a `--token` flag**. Putting secrets in command-line arguments exposes them in shell history and process listings.
+
+```bash
+# Bad — token visible in shell history and process listings
+vercel deploy --token "vca_abc123"
+
+# Good — CLI reads VERCEL_TOKEN from the environment
+export VERCEL_TOKEN="vca_abc123"
+vercel deploy
+```
+
+## Step 2: Locate the Project and Team
+
+Similarly, check for the project ID and team scope. These let the CLI target the right project without needing `vercel link`.
+
+```bash
+# Check environment
+printenv VERCEL_PROJECT_ID
+printenv VERCEL_ORG_ID
+
+# Or check .env
+grep -i 'vercel' .env 2>/dev/null
+```
+
+**If you have a project URL** (e.g. `https://vercel.com/my-team/my-project`), extract the team slug:
+
+```bash
+# e.g. "my-team" from "https://vercel.com/my-team/my-project"
+echo "$PROJECT_URL" | sed 's|https://vercel.com/||' | cut -d/ -f1
+```
+
+**If you have both `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` in your environment**, export them — the CLI will use these automatically and skip any `.vercel/` directory:
+
+```bash
+export VERCEL_ORG_ID="<org-id>"
+export VERCEL_PROJECT_ID="<project-id>"
+```
+
+Note: `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` must be set together — setting only one causes an error.
+
+## CLI Setup
+
+Ensure the Vercel CLI is installed and up to date:
+
+```bash
+npm install -g vercel
+vercel --version
+```
+
+## Deploying a Project
+
+Always deploy as **preview** unless the user explicitly requests production. Choose a method based on what you have available.
+
+### Quick Deploy (have project ID — no linking needed)
+
+When `VERCEL_TOKEN` and `VERCEL_PROJECT_ID` are set in the environment, deploy directly:
+
+```bash
+vercel deploy -y --no-wait
+```
+
+With a team scope (either via `VERCEL_ORG_ID` or `--scope`):
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Production (only when explicitly requested):
+
+```bash
+vercel deploy --prod --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Full Deploy Flow (no project ID — need to link)
+
+Use this when you have a token and team but no pre-existing project ID.
+
+#### Check project state first
+
+```bash
+# Does the project have a git remote?
+git remote get-url origin 2>/dev/null
+
+# Is it already linked to a Vercel project?
+cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
+```
+
+#### Link the project
+
+**With git remote (preferred):**
+
+```bash
+vercel link --repo --scope <team-slug> -y
+```
+
+Reads the git remote and connects to the matching Vercel project. Creates `.vercel/repo.json`. More reliable than plain `vercel link`, which matches by directory name.
+
+**Without git remote:**
+
+```bash
+vercel link --scope <team-slug> -y
+```
+
+Creates `.vercel/project.json`.
+
+**Link to a specific project by name:**
+
+```bash
+vercel link --project <project-name> --scope <team-slug> -y
+```
+
+If the project is already linked, check `orgId` in `.vercel/project.json` or `.vercel/repo.json` to verify it matches the intended team.
+
+#### Deploy after linking
+
+**A) Git Push Deploy — has git remote (preferred)**
+
+Git pushes trigger automatic Vercel deployments.
+
+1. **Ask the user before pushing.** Never push without explicit approval.
+2. Commit and push:
+   ```bash
+   git add .
+   git commit -m "deploy: <description of changes>"
+   git push
+   ```
+3. Vercel builds automatically. Non-production branches get preview deployments.
+4. Retrieve the deployment URL:
+   ```bash
+   sleep 5
+   vercel ls --format json --scope <team-slug>
+   ```
+   Find the latest entry in the `deployments` array.
+
+**B) CLI Deploy — no git remote**
+
+```bash
+vercel deploy --scope <team-slug> -y --no-wait
+```
+
+Check status:
+
+```bash
+vercel inspect <deployment-url>
+```
+
+### Deploying from a Remote Repository (code not cloned locally)
+
+1. Clone the repository:
+   ```bash
+   git clone <repo-url>
+   cd <repo-name>
+   ```
+2. Link to Vercel:
+   ```bash
+   vercel link --repo --scope <team-slug> -y
+   ```
+3. Deploy via git push (if you have push access) or CLI deploy.
+
+### About `.vercel/` Directory
+
+A linked project has either:
+- `.vercel/project.json` — from `vercel link`. Contains `projectId` and `orgId`.
+- `.vercel/repo.json` — from `vercel link --repo`. Contains `orgId`, `remoteName`, and a `projects` map.
+
+Not needed when `VERCEL_ORG_ID` + `VERCEL_PROJECT_ID` are both set in the environment.
+
+**Do NOT** run `vercel project inspect` or `vercel link` in an unlinked directory to detect state — they will interactively prompt or silently link as a side-effect. `vercel ls` is safe (in an unlinked directory it defaults to showing all deployments for the scope). `vercel whoami` is safe anywhere.
+
+## Managing Environment Variables
+
+```bash
+# Set for all environments
+echo "value" | vercel env add VAR_NAME --scope <team-slug>
+
+# Set for a specific environment (production, preview, development)
+echo "value" | vercel env add VAR_NAME production --scope <team-slug>
+
+# List environment variables
+vercel env ls --scope <team-slug>
+
+# Pull env vars to local .env.local file
+vercel env pull --scope <team-slug>
+
+# Remove a variable
+vercel env rm VAR_NAME --scope <team-slug> -y
+```
+
+## Inspecting Deployments
+
+```bash
+# List recent deployments
+vercel ls --format json --scope <team-slug>
+
+# Inspect a specific deployment
+vercel inspect <deployment-url>
+
+# View build logs (requires Vercel CLI v35+)
+vercel inspect <deployment-url> --logs
+
+# View runtime request logs (follows live by default; add --no-follow for a one-shot snapshot)
+vercel logs <deployment-url>
+```
+
+## Managing Domains
+
+```bash
+# List domains
+vercel domains ls --scope <team-slug>
+
+# Add a domain to the project — linked or env-linked directory (1 arg)
+vercel domains add <domain> --scope <team-slug>
+
+# Add a domain — unlinked directory (requires <project> positional)
+vercel domains add <domain> <project> --scope <team-slug>
+```
+
+## Stripe Projects Plan Changes
+
+If this project is managed by Stripe Projects. **Ask the user before running any paid or destructive plan change** — upgrades bill a real card, downgrades remove seats.
+
+First run `stripe projects status --json` to confirm the Vercel resource's local name. The examples below assume the default (`vercel-plan`); substitute the actual name if it was renamed at `stripe projects add` time.
+
+- **Upgrade to Pro:** `stripe projects add vercel/pro` (or `stripe projects upgrade vercel-plan pro`)
+- **Downgrade to Hobby:** `stripe projects downgrade vercel-plan hobby`
+
+### What Pro gives you
+
+- $20/month platform fee, includes $20/month of usage credit.
+- Turbo build machines (30 vCPUs, 60 GB memory) by default for new projects — significantly faster builds than Hobby.
+- 1 deploying seat + unlimited free Viewer seats (read-only collaborators, preview comments).
+- Higher included allocations (1 TB Fast Data Transfer, 10M Edge Requests per month).
+- Paid add-ons available: SAML SSO, HIPAA BAA, Flags Explorer, Observability Plus, Speed Insights, Web Analytics Plus.
+
+Full details: https://vercel.com/docs/plans/pro-plan
+
+## Working Agreement
+
+- **Never pass `VERCEL_TOKEN` as a `--token` flag.** Export it as an environment variable and let the CLI read it natively.
+- **Check the environment for tokens before asking the user.** Look in the current env and `.env` files first.
+- **Default to preview deployments.** Only deploy to production when explicitly asked.
+- **Ask before pushing to git.** Never push commits without the user's approval.
+- **Do not modify `.vercel/` files directly.** The CLI manages this directory. Reading them (e.g. to verify `orgId`) is fine.
+- **Do not curl/fetch deployed URLs to verify.** Just return the link to the user.
+- **Use `--format json`** when structured output will help with follow-up steps.
+- **Use `-y`** on commands that prompt for confirmation to avoid interactive blocking.
+
+## Troubleshooting
+
+### Token not found
+
+Check the environment and any `.env` files present:
+
+```bash
+printenv | grep -i vercel
+grep -i vercel .env 2>/dev/null
+```
+
+### Authentication error
+
+If the CLI fails with `Authentication required`:
+- The token may be expired or invalid.
+- Verify: `vercel whoami` (uses `VERCEL_TOKEN` from environment).
+- Ask the user for a fresh token.
+
+### Wrong team
+
+Verify the scope is correct:
+
+```bash
+vercel whoami --scope <team-slug>
+```
+
+### Build failure
+
+Check the build logs:
+
+```bash
+vercel inspect <deployment-url> --logs
+```
+
+Common causes:
+- Missing dependencies — ensure `package.json` is complete and committed.
+- Missing environment variables — add with `vercel env add`.
+- Framework misconfiguration — check `vercel.json`. Vercel auto-detects frameworks (Next.js, Remix, Vite, etc.) from `package.json`; override with `vercel.json` if detection is wrong.
+
+### CLI not installed
+
+```bash
+npm install -g vercel
+```
diff --git a/skills/vercel-composition-patterns/AGENTS.md b/skills/vercel-composition-patterns/AGENTS.md
new file mode 100644
index 00000000..558bf9aa
--- /dev/null
+++ b/skills/vercel-composition-patterns/AGENTS.md
@@ -0,0 +1,946 @@
+# React Composition Patterns
+
+**Version 1.0.0**  
+Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React codebases using composition. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.
+
+---
+
+## Table of Contents
+
+1. [Component Architecture](#1-component-architecture) — **HIGH**
+   - 1.1 [Avoid Boolean Prop Proliferation](#11-avoid-boolean-prop-proliferation)
+   - 1.2 [Use Compound Components](#12-use-compound-components)
+2. [State Management](#2-state-management) — **MEDIUM**
+   - 2.1 [Decouple State Management from UI](#21-decouple-state-management-from-ui)
+   - 2.2 [Define Generic Context Interfaces for Dependency Injection](#22-define-generic-context-interfaces-for-dependency-injection)
+   - 2.3 [Lift State into Provider Components](#23-lift-state-into-provider-components)
+3. [Implementation Patterns](#3-implementation-patterns) — **MEDIUM**
+   - 3.1 [Create Explicit Component Variants](#31-create-explicit-component-variants)
+   - 3.2 [Prefer Composing Children Over Render Props](#32-prefer-composing-children-over-render-props)
+4. [React 19 APIs](#4-react-19-apis) — **MEDIUM**
+   - 4.1 [React 19 API Changes](#41-react-19-api-changes)
+
+---
+
+## 1. Component Architecture
+
+**Impact: HIGH**
+
+Fundamental patterns for structuring components to avoid prop
+proliferation and enable flexible composition.
+
+### 1.1 Avoid Boolean Prop Proliferation
+
+**Impact: CRITICAL (prevents unmaintainable component variants)**
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+
+component behavior. Each boolean doubles possible states and creates
+
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect: boolean props create exponential complexity**
+
+```tsx
+function Composer({
+  onSubmit,
+  isThread,
+  channelId,
+  isDMThread,
+  dmId,
+  isEditing,
+  isForwarding,
+}: Props) {
+  return (
+    <form>
+      <Header />
+      <Input />
+      {isDMThread ? (
+        <AlsoSendToDMField id={dmId} />
+      ) : isThread ? (
+        <AlsoSendToChannelField id={channelId} />
+      ) : null}
+      {isEditing ? (
+        <EditActions />
+      ) : isForwarding ? (
+        <ForwardActions />
+      ) : (
+        <DefaultActions />
+      )}
+      <Footer onSubmit={onSubmit} />
+    </form>
+  )
+}
+```
+
+**Correct: composition eliminates conditionals**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Attachments />
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <AlsoSendToChannelField id={channelId} />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+
+sharing a single monolithic parent.
+
+### 1.2 Use Compound Components
+
+**Impact: HIGH (enables flexible composition without prop drilling)**
+
+Structure complex components as compound components with a shared context. Each
+
+subcomponent accesses shared state via context, not props. Consumers compose the
+
+pieces they need.
+
+**Incorrect: monolithic component with render props**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+  showAttachments,
+  showFormatting,
+  showEmojis,
+}: Props) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {showAttachments && <Attachments />}
+      {renderFooter ? (
+        renderFooter()
+      ) : (
+        <Footer>
+          {showFormatting && <Formatting />}
+          {showEmojis && <Emojis />}
+          {renderActions?.()}
+        </Footer>
+      )}
+    </form>
+  )
+}
+```
+
+**Correct: compound components with shared context**
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+
+function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
+  return (
+    <ComposerContext value={{ state, actions, meta }}>
+      {children}
+    </ComposerContext>
+  )
+}
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta: { inputRef },
+  } = use(ComposerContext)
+  return (
+    <TextInput
+      ref={inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+
+function ComposerSubmit() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Send</Button>
+}
+
+// Export as compound component
+const Composer = {
+  Provider: ComposerProvider,
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  Header: ComposerHeader,
+  Footer: ComposerFooter,
+  Attachments: ComposerAttachments,
+  Formatting: ComposerFormatting,
+  Emojis: ComposerEmojis,
+}
+```
+
+**Usage:**
+
+```tsx
+<Composer.Provider state={state} actions={actions} meta={meta}>
+  <Composer.Frame>
+    <Composer.Header />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Submit />
+    </Composer.Footer>
+  </Composer.Frame>
+</Composer.Provider>
+```
+
+Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
+
+---
+
+## 2. State Management
+
+**Impact: MEDIUM**
+
+Patterns for lifting state and managing shared context across
+composed components.
+
+### 2.1 Decouple State Management from UI
+
+**Impact: MEDIUM (enables swapping state implementations without changing UI)**
+
+The provider component should be the only place that knows how state is managed.
+
+UI components consume the context interface—they don't know if state comes from
+
+useState, Zustand, or a server sync.
+
+**Incorrect: UI coupled to state implementation**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+  // UI component knows about global state implementation
+  const state = useGlobalChannelState(channelId)
+  const { submit, updateInput } = useChannelSync(channelId)
+
+  return (
+    <Composer.Frame>
+      <Composer.Input
+        value={state.input}
+        onChange={(text) => sync.updateInput(text)}
+      />
+      <Composer.Submit onPress={() => sync.submit()} />
+    </Composer.Frame>
+  )
+}
+```
+
+**Correct: state management isolated in provider**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+  channelId,
+  children,
+}: {
+  channelId: string
+  children: React.ReactNode
+}) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update, submit }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+  return (
+    <ChannelProvider channelId={channelId}>
+      <ChannelComposer />
+    </ChannelProvider>
+  )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+
+  return (
+    <Composer.Provider state={state} actions={{ update, submit }}>
+      {children}
+    </Composer.Provider>
+  )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+
+depends on the context interface, not the implementation.
+
+### 2.2 Define Generic Context Interfaces for Dependency Injection
+
+**Impact: HIGH (enables dependency-injectable state across use-cases)**
+
+Define a **generic interface** for your component context with three parts:
+
+`state`, `actions`, and `meta`. This interface is a contract that any provider
+
+can implement—enabling the same UI components to work with completely different
+
+state implementations.
+
+**Core principle:** Lift state, compose internals, make state
+
+dependency-injectable.
+
+**Incorrect: UI coupled to specific state implementation**
+
+```tsx
+function ComposerInput() {
+  // Tightly coupled to a specific hook
+  const { input, setInput } = useChannelComposerState()
+  return <TextInput value={input} onChangeText={setInput} />
+}
+```
+
+**Correct: generic interface enables dependency injection**
+
+```tsx
+// Define a GENERIC interface that any provider can implement
+interface ComposerState {
+  input: string
+  attachments: Attachment[]
+  isSubmitting: boolean
+}
+
+interface ComposerActions {
+  update: (updater: (state: ComposerState) => ComposerState) => void
+  submit: () => void
+}
+
+interface ComposerMeta {
+  inputRef: React.RefObject<TextInput>
+}
+
+interface ComposerContextValue {
+  state: ComposerState
+  actions: ComposerActions
+  meta: ComposerMeta
+}
+
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+```
+
+**UI components consume the interface, not the implementation:**
+
+```tsx
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta,
+  } = use(ComposerContext)
+
+  // This component works with ANY provider that implements the interface
+  return (
+    <TextInput
+      ref={meta.inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+```
+
+**Different providers implement the same interface:**
+
+```tsx
+// Provider A: Local state for ephemeral forms
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const inputRef = useRef(null)
+  const submit = useForwardMessage()
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update: setState, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+
+// Provider B: Global synced state for channels
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+```
+
+**The same composed UI works with both:**
+
+```tsx
+// Works with ForwardMessageProvider (local state)
+<ForwardMessageProvider>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ForwardMessageProvider>
+
+// Works with ChannelProvider (global synced state)
+<ChannelProvider channelId="abc">
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ChannelProvider>
+```
+
+**Custom UI outside the component can access state and actions:**
+
+```tsx
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        {/* The composer UI */}
+        <Composer.Frame>
+          <Composer.Input placeholder="Add a message, if you'd like." />
+          <Composer.Footer>
+            <Composer.Formatting />
+            <Composer.Emojis />
+          </Composer.Footer>
+        </Composer.Frame>
+
+        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
+        <MessagePreview />
+
+        {/* Actions at the bottom of the dialog */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton />
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
+function ForwardButton() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Forward</Button>
+}
+
+// This preview lives OUTSIDE Composer.Frame but can read composer's state!
+function MessagePreview() {
+  const { state } = use(ComposerContext)
+  return <Preview message={state.input} attachments={state.attachments} />
+}
+```
+
+The provider boundary is what matters—not the visual nesting. Components that
+
+need shared state don't have to be inside the `Composer.Frame`. They just need
+
+to be within the provider.
+
+The `ForwardButton` and `MessagePreview` are not visually inside the composer
+
+box, but they can still access its state and actions. This is the power of
+
+lifting state into providers.
+
+The UI is reusable bits you compose together. The state is dependency-injected
+
+by the provider. Swap the provider, keep the UI.
+
+### 2.3 Lift State into Provider Components
+
+**Impact: HIGH (enables state sharing outside component boundaries)**
+
+Move state management into dedicated provider components. This allows sibling
+
+components outside the main UI to access and modify state without prop drilling
+
+or awkward refs.
+
+**Incorrect: state trapped inside component**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect: useEffect to sync state up**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect: reading state from ref on submit**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct: state lifted to provider**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+
+submit action because it's within the provider. Even though it's a one-off
+
+component, it can still access the composer's state and actions from outside the
+
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+
+nested inside each other—they just need to be within the same provider.
+
+---
+
+## 3. Implementation Patterns
+
+**Impact: MEDIUM**
+
+Specific techniques for implementing compound components and
+context providers.
+
+### 3.1 Create Explicit Component Variants
+
+**Impact: MEDIUM (self-documenting code, no hidden conditionals)**
+
+Instead of one component with many boolean props, create explicit variant
+
+components. Each variant composes the pieces it needs. The code documents
+
+itself.
+
+**Incorrect: one component, many modes**
+
+```tsx
+// What does this component actually render?
+<Composer
+  isThread
+  isEditing={false}
+  channelId='abc'
+  showAttachments
+  showFormatting={false}
+/>
+```
+
+**Correct: explicit variants**
+
+```tsx
+// Immediately clear what this renders
+<ThreadComposer channelId="abc" />
+
+// Or
+<EditMessageComposer messageId="xyz" />
+
+// Or
+<ForwardMessageComposer messageId="123" />
+```
+
+Each implementation is unique, explicit and self-contained. Yet they can each
+
+use shared parts.
+
+**Implementation:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <ThreadProvider channelId={channelId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <AlsoSendToChannelField channelId={channelId} />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Submit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ThreadProvider>
+  )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <EditMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.CancelEdit />
+          <Composer.SaveEdit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </EditMessageProvider>
+  )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <ForwardMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input placeholder="Add a message, if you'd like." />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Mentions />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ForwardMessageProvider>
+  )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+
+- What UI elements it includes
+
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
+
+### 3.2 Prefer Composing Children Over Render Props
+
+**Impact: MEDIUM (cleaner composition, better readability)**
+
+Use `children` for composition instead of `renderX` props. Children are more
+
+readable, compose naturally, and don't require understanding callback
+
+signatures.
+
+**Incorrect: render props**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+}: {
+  renderHeader?: () => React.ReactNode
+  renderFooter?: () => React.ReactNode
+  renderActions?: () => React.ReactNode
+}) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {renderFooter ? renderFooter() : <DefaultFooter />}
+      {renderActions?.()}
+    </form>
+  )
+}
+
+// Usage is awkward and inflexible
+return (
+  <Composer
+    renderHeader={() => <CustomHeader />}
+    renderFooter={() => (
+      <>
+        <Formatting />
+        <Emojis />
+      </>
+    )}
+    renderActions={() => <SubmitButton />}
+  />
+)
+```
+
+**Correct: compound components with children**
+
+```tsx
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerFooter({ children }: { children: React.ReactNode }) {
+  return <footer className='flex'>{children}</footer>
+}
+
+// Usage is flexible
+return (
+  <Composer.Frame>
+    <CustomHeader />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Emojis />
+      <SubmitButton />
+    </Composer.Footer>
+  </Composer.Frame>
+)
+```
+
+**When render props are appropriate:**
+
+```tsx
+// Render props work well when you need to pass data back
+<List
+  data={items}
+  renderItem={({ item, index }) => <Item item={item} index={index} />}
+/>
+```
+
+Use render props when the parent needs to provide data or state to the child.
+
+Use children when composing static structure.
+
+---
+
+## 4. React 19 APIs
+
+**Impact: MEDIUM**
+
+React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
+
+### 4.1 React 19 API Changes
+
+**Impact: MEDIUM (cleaner component definitions and context usage)**
+
+> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
+
+In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
+
+**Incorrect: forwardRef in React 19**
+
+```tsx
+const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
+  return <TextInput ref={ref} {...props} />
+})
+```
+
+**Correct: ref as a regular prop**
+
+```tsx
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
+  return <TextInput ref={ref} {...props} />
+}
+```
+
+**Incorrect: useContext in React 19**
+
+```tsx
+const value = useContext(MyContext)
+```
+
+**Correct: use instead of useContext**
+
+```tsx
+const value = use(MyContext)
+```
+
+`use()` can also be called conditionally, unlike `useContext()`.
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://react.dev/learn/passing-data-deeply-with-context](https://react.dev/learn/passing-data-deeply-with-context)
+3. [https://react.dev/reference/react/use](https://react.dev/reference/react/use)
diff --git a/skills/vercel-composition-patterns/README.md b/skills/vercel-composition-patterns/README.md
new file mode 100644
index 00000000..01f359b0
--- /dev/null
+++ b/skills/vercel-composition-patterns/README.md
@@ -0,0 +1,60 @@
+# React Composition Patterns
+
+A structured repository for React composition patterns that scale. These
+patterns help avoid boolean prop proliferation by using compound components,
+lifting state, and composing internals.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Component Architecture (CRITICAL)
+
+- `architecture-avoid-boolean-props.md` - Don't add boolean props to customize
+  behavior
+- `architecture-compound-components.md` - Structure as compound components with
+  shared context
+
+### State Management (HIGH)
+
+- `state-lift-state.md` - Lift state into provider components
+- `state-context-interface.md` - Define clear context interfaces
+  (state/actions/meta)
+- `state-decouple-implementation.md` - Decouple state management from UI
+
+### Implementation Patterns (MEDIUM)
+
+- `patterns-children-over-render-props.md` - Prefer children over renderX props
+- `patterns-explicit-variants.md` - Create explicit component variants
+
+## Core Principles
+
+1. **Composition over configuration** — Instead of adding props, let consumers
+   compose
+2. **Lift your state** — State in providers, not trapped in components
+3. **Compose your internals** — Subcomponents access context, not props
+4. **Explicit variants** — Create ThreadComposer, EditComposer, not Composer
+   with isThread
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `architecture-` for Component Architecture
+   - `state-` for State Management
+   - `patterns-` for Implementation Patterns
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Impact Levels
+
+- `CRITICAL` - Foundational patterns, prevents unmaintainable code
+- `HIGH` - Significant maintainability improvements
+- `MEDIUM` - Good practices for cleaner code
diff --git a/skills/vercel-composition-patterns/SKILL.md b/skills/vercel-composition-patterns/SKILL.md
new file mode 100644
index 00000000..d07025bf
--- /dev/null
+++ b/skills/vercel-composition-patterns/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: vercel-composition-patterns
+description:
+  React composition patterns that scale. Use when refactoring components with
+  boolean prop proliferation, building flexible component libraries, or
+  designing reusable APIs. Triggers on tasks involving compound components,
+  render props, context providers, or component architecture. Includes React 19
+  API changes.
+license: MIT
+metadata:
+  author: vercel
+  version: '1.0.0'
+---
+
+# React Composition Patterns
+
+Composition patterns for building flexible, maintainable React components. Avoid
+boolean prop proliferation by using compound components, lifting state, and
+composing internals. These patterns make codebases easier for both humans and AI
+agents to work with as they scale.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Refactoring components with many boolean props
+- Building reusable component libraries
+- Designing flexible component APIs
+- Reviewing component architecture
+- Working with compound components or context providers
+
+## Rule Categories by Priority
+
+| Priority | Category                | Impact | Prefix          |
+| -------- | ----------------------- | ------ | --------------- |
+| 1        | Component Architecture  | HIGH   | `architecture-` |
+| 2        | State Management        | MEDIUM | `state-`        |
+| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
+| 4        | React 19 APIs           | MEDIUM | `react19-`      |
+
+## Quick Reference
+
+### 1. Component Architecture (HIGH)
+
+- `architecture-avoid-boolean-props` - Don't add boolean props to customize
+  behavior; use composition
+- `architecture-compound-components` - Structure complex components with shared
+  context
+
+### 2. State Management (MEDIUM)
+
+- `state-decouple-implementation` - Provider is the only place that knows how
+  state is managed
+- `state-context-interface` - Define generic interface with state, actions, meta
+  for dependency injection
+- `state-lift-state` - Move state into provider components for sibling access
+
+### 3. Implementation Patterns (MEDIUM)
+
+- `patterns-explicit-variants` - Create explicit variant components instead of
+  boolean modes
+- `patterns-children-over-render-props` - Use children for composition instead
+  of renderX props
+
+### 4. React 19 APIs (MEDIUM)
+
+> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
+
+- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/architecture-avoid-boolean-props.md
+rules/state-context-interface.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel-composition-patterns/metadata.json b/skills/vercel-composition-patterns/metadata.json
new file mode 100644
index 00000000..3470b744
--- /dev/null
+++ b/skills/vercel-composition-patterns/metadata.json
@@ -0,0 +1,11 @@
+{
+  "version": "1.0.0",
+  "organization": "Engineering",
+  "date": "January 2026",
+  "abstract": "Composition patterns for building flexible, maintainable React components. Avoid boolean prop proliferation by using compound components, lifting state, and composing internals. These patterns make codebases easier for both humans and AI agents to work with as they scale.",
+  "references": [
+    "https://react.dev",
+    "https://react.dev/learn/passing-data-deeply-with-context",
+    "https://react.dev/reference/react/use"
+  ]
+}
diff --git a/skills/vercel-composition-patterns/rules/_sections.md b/skills/vercel-composition-patterns/rules/_sections.md
new file mode 100644
index 00000000..f921dd41
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/_sections.md
@@ -0,0 +1,29 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Component Architecture (architecture)
+
+**Impact:** HIGH  
+**Description:** Fundamental patterns for structuring components to avoid prop
+proliferation and enable flexible composition.
+
+## 2. State Management (state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for lifting state and managing shared context across
+composed components.
+
+## 3. Implementation Patterns (patterns)
+
+**Impact:** MEDIUM  
+**Description:** Specific techniques for implementing compound components and
+context providers.
+
+## 4. React 19 APIs (react19)
+
+**Impact:** MEDIUM  
+**Description:** React 19+ only. Don't use `forwardRef`; use `use()` instead of `useContext()`.
diff --git a/skills/vercel-composition-patterns/rules/_template.md b/skills/vercel-composition-patterns/rules/_template.md
new file mode 100644
index 00000000..119a3016
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/_template.md
@@ -0,0 +1,24 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: brief description of impact
+tags: composition, components
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect:**
+
+```tsx
+// Bad code example
+```
+
+**Correct:**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
diff --git a/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md b/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
new file mode 100644
index 00000000..ccee19ce
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
@@ -0,0 +1,100 @@
+---
+title: Avoid Boolean Prop Proliferation
+impact: CRITICAL
+impactDescription: prevents unmaintainable component variants
+tags: composition, props, architecture
+---
+
+## Avoid Boolean Prop Proliferation
+
+Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize
+component behavior. Each boolean doubles possible states and creates
+unmaintainable conditional logic. Use composition instead.
+
+**Incorrect (boolean props create exponential complexity):**
+
+```tsx
+function Composer({
+  onSubmit,
+  isThread,
+  channelId,
+  isDMThread,
+  dmId,
+  isEditing,
+  isForwarding,
+}: Props) {
+  return (
+    <form>
+      <Header />
+      <Input />
+      {isDMThread ? (
+        <AlsoSendToDMField id={dmId} />
+      ) : isThread ? (
+        <AlsoSendToChannelField id={channelId} />
+      ) : null}
+      {isEditing ? (
+        <EditActions />
+      ) : isForwarding ? (
+        <ForwardActions />
+      ) : (
+        <DefaultActions />
+      )}
+      <Footer onSubmit={onSubmit} />
+    </form>
+  )
+}
+```
+
+**Correct (composition eliminates conditionals):**
+
+```tsx
+// Channel composer
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Attachments />
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Thread composer - adds "also send to channel" field
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <AlsoSendToChannelField id={channelId} />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Edit composer - different footer actions
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Formatting />
+        <Composer.Emojis />
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+```
+
+Each variant is explicit about what it renders. We can share internals without
+sharing a single monolithic parent.
diff --git a/skills/vercel-composition-patterns/rules/architecture-compound-components.md b/skills/vercel-composition-patterns/rules/architecture-compound-components.md
new file mode 100644
index 00000000..e5e3043c
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/architecture-compound-components.md
@@ -0,0 +1,112 @@
+---
+title: Use Compound Components
+impact: HIGH
+impactDescription: enables flexible composition without prop drilling
+tags: composition, compound-components, architecture
+---
+
+## Use Compound Components
+
+Structure complex components as compound components with a shared context. Each
+subcomponent accesses shared state via context, not props. Consumers compose the
+pieces they need.
+
+**Incorrect (monolithic component with render props):**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+  showAttachments,
+  showFormatting,
+  showEmojis,
+}: Props) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {showAttachments && <Attachments />}
+      {renderFooter ? (
+        renderFooter()
+      ) : (
+        <Footer>
+          {showFormatting && <Formatting />}
+          {showEmojis && <Emojis />}
+          {renderActions?.()}
+        </Footer>
+      )}
+    </form>
+  )
+}
+```
+
+**Correct (compound components with shared context):**
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+
+function ComposerProvider({ children, state, actions, meta }: ProviderProps) {
+  return (
+    <ComposerContext value={{ state, actions, meta }}>
+      {children}
+    </ComposerContext>
+  )
+}
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta: { inputRef },
+  } = use(ComposerContext)
+  return (
+    <TextInput
+      ref={inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+
+function ComposerSubmit() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Send</Button>
+}
+
+// Export as compound component
+const Composer = {
+  Provider: ComposerProvider,
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  Header: ComposerHeader,
+  Footer: ComposerFooter,
+  Attachments: ComposerAttachments,
+  Formatting: ComposerFormatting,
+  Emojis: ComposerEmojis,
+}
+```
+
+**Usage:**
+
+```tsx
+<Composer.Provider state={state} actions={actions} meta={meta}>
+  <Composer.Frame>
+    <Composer.Header />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Submit />
+    </Composer.Footer>
+  </Composer.Frame>
+</Composer.Provider>
+```
+
+Consumers explicitly compose exactly what they need. No hidden conditionals. And the state, actions and meta are dependency-injected by a parent provider, allowing multiple usages of the same component structure.
diff --git a/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md b/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
new file mode 100644
index 00000000..d4345ee3
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
@@ -0,0 +1,87 @@
+---
+title: Prefer Composing Children Over Render Props
+impact: MEDIUM
+impactDescription: cleaner composition, better readability
+tags: composition, children, render-props
+---
+
+## Prefer Children Over Render Props
+
+Use `children` for composition instead of `renderX` props. Children are more
+readable, compose naturally, and don't require understanding callback
+signatures.
+
+**Incorrect (render props):**
+
+```tsx
+function Composer({
+  renderHeader,
+  renderFooter,
+  renderActions,
+}: {
+  renderHeader?: () => React.ReactNode
+  renderFooter?: () => React.ReactNode
+  renderActions?: () => React.ReactNode
+}) {
+  return (
+    <form>
+      {renderHeader?.()}
+      <Input />
+      {renderFooter ? renderFooter() : <DefaultFooter />}
+      {renderActions?.()}
+    </form>
+  )
+}
+
+// Usage is awkward and inflexible
+return (
+  <Composer
+    renderHeader={() => <CustomHeader />}
+    renderFooter={() => (
+      <>
+        <Formatting />
+        <Emojis />
+      </>
+    )}
+    renderActions={() => <SubmitButton />}
+  />
+)
+```
+
+**Correct (compound components with children):**
+
+```tsx
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>
+}
+
+function ComposerFooter({ children }: { children: React.ReactNode }) {
+  return <footer className='flex'>{children}</footer>
+}
+
+// Usage is flexible
+return (
+  <Composer.Frame>
+    <CustomHeader />
+    <Composer.Input />
+    <Composer.Footer>
+      <Composer.Formatting />
+      <Composer.Emojis />
+      <SubmitButton />
+    </Composer.Footer>
+  </Composer.Frame>
+)
+```
+
+**When render props are appropriate:**
+
+```tsx
+// Render props work well when you need to pass data back
+<List
+  data={items}
+  renderItem={({ item, index }) => <Item item={item} index={index} />}
+/>
+```
+
+Use render props when the parent needs to provide data or state to the child.
+Use children when composing static structure.
diff --git a/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md b/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
new file mode 100644
index 00000000..56e32e8b
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
@@ -0,0 +1,100 @@
+---
+title: Create Explicit Component Variants
+impact: MEDIUM
+impactDescription: self-documenting code, no hidden conditionals
+tags: composition, variants, architecture
+---
+
+## Create Explicit Component Variants
+
+Instead of one component with many boolean props, create explicit variant
+components. Each variant composes the pieces it needs. The code documents
+itself.
+
+**Incorrect (one component, many modes):**
+
+```tsx
+// What does this component actually render?
+<Composer
+  isThread
+  isEditing={false}
+  channelId='abc'
+  showAttachments
+  showFormatting={false}
+/>
+```
+
+**Correct (explicit variants):**
+
+```tsx
+// Immediately clear what this renders
+<ThreadComposer channelId="abc" />
+
+// Or
+<EditMessageComposer messageId="xyz" />
+
+// Or
+<ForwardMessageComposer messageId="123" />
+```
+
+Each implementation is unique, explicit and self-contained. Yet they can each
+use shared parts.
+
+**Implementation:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <ThreadProvider channelId={channelId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <AlsoSendToChannelField channelId={channelId} />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Submit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ThreadProvider>
+  )
+}
+
+function EditMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <EditMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.CancelEdit />
+          <Composer.SaveEdit />
+        </Composer.Footer>
+      </Composer.Frame>
+    </EditMessageProvider>
+  )
+}
+
+function ForwardMessageComposer({ messageId }: { messageId: string }) {
+  return (
+    <ForwardMessageProvider messageId={messageId}>
+      <Composer.Frame>
+        <Composer.Input placeholder="Add a message, if you'd like." />
+        <Composer.Footer>
+          <Composer.Formatting />
+          <Composer.Emojis />
+          <Composer.Mentions />
+        </Composer.Footer>
+      </Composer.Frame>
+    </ForwardMessageProvider>
+  )
+}
+```
+
+Each variant is explicit about:
+
+- What provider/state it uses
+- What UI elements it includes
+- What actions are available
+
+No boolean prop combinations to reason about. No impossible states.
diff --git a/skills/vercel-composition-patterns/rules/react19-no-forwardref.md b/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
new file mode 100644
index 00000000..e0d8f8a7
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
@@ -0,0 +1,42 @@
+---
+title: React 19 API Changes
+impact: MEDIUM
+impactDescription: cleaner component definitions and context usage
+tags: react19, refs, context, hooks
+---
+
+## React 19 API Changes
+
+> **⚠️ React 19+ only.** Skip this if you're on React 18 or earlier.
+
+In React 19, `ref` is now a regular prop (no `forwardRef` wrapper needed), and `use()` replaces `useContext()`.
+
+**Incorrect (forwardRef in React 19):**
+
+```tsx
+const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
+  return <TextInput ref={ref} {...props} />
+})
+```
+
+**Correct (ref as a regular prop):**
+
+```tsx
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<TextInput> }) {
+  return <TextInput ref={ref} {...props} />
+}
+```
+
+**Incorrect (useContext in React 19):**
+
+```tsx
+const value = useContext(MyContext)
+```
+
+**Correct (use instead of useContext):**
+
+```tsx
+const value = use(MyContext)
+```
+
+`use()` can also be called conditionally, unlike `useContext()`.
diff --git a/skills/vercel-composition-patterns/rules/state-context-interface.md b/skills/vercel-composition-patterns/rules/state-context-interface.md
new file mode 100644
index 00000000..d961bede
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/state-context-interface.md
@@ -0,0 +1,191 @@
+---
+title: Define Generic Context Interfaces for Dependency Injection
+impact: HIGH
+impactDescription: enables dependency-injectable state across use-cases
+tags: composition, context, state, typescript, dependency-injection
+---
+
+## Define Generic Context Interfaces for Dependency Injection
+
+Define a **generic interface** for your component context with three parts:
+`state`, `actions`, and `meta`. This interface is a contract that any provider
+can implement—enabling the same UI components to work with completely different
+state implementations.
+
+**Core principle:** Lift state, compose internals, make state
+dependency-injectable.
+
+**Incorrect (UI coupled to specific state implementation):**
+
+```tsx
+function ComposerInput() {
+  // Tightly coupled to a specific hook
+  const { input, setInput } = useChannelComposerState()
+  return <TextInput value={input} onChangeText={setInput} />
+}
+```
+
+**Correct (generic interface enables dependency injection):**
+
+```tsx
+// Define a GENERIC interface that any provider can implement
+interface ComposerState {
+  input: string
+  attachments: Attachment[]
+  isSubmitting: boolean
+}
+
+interface ComposerActions {
+  update: (updater: (state: ComposerState) => ComposerState) => void
+  submit: () => void
+}
+
+interface ComposerMeta {
+  inputRef: React.RefObject<TextInput>
+}
+
+interface ComposerContextValue {
+  state: ComposerState
+  actions: ComposerActions
+  meta: ComposerMeta
+}
+
+const ComposerContext = createContext<ComposerContextValue | null>(null)
+```
+
+**UI components consume the interface, not the implementation:**
+
+```tsx
+function ComposerInput() {
+  const {
+    state,
+    actions: { update },
+    meta,
+  } = use(ComposerContext)
+
+  // This component works with ANY provider that implements the interface
+  return (
+    <TextInput
+      ref={meta.inputRef}
+      value={state.input}
+      onChangeText={(text) => update((s) => ({ ...s, input: text }))}
+    />
+  )
+}
+```
+
+**Different providers implement the same interface:**
+
+```tsx
+// Provider A: Local state for ephemeral forms
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const inputRef = useRef(null)
+  const submit = useForwardMessage()
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update: setState, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+
+// Provider B: Global synced state for channels
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <ComposerContext
+      value={{
+        state,
+        actions: { update, submit },
+        meta: { inputRef },
+      }}
+    >
+      {children}
+    </ComposerContext>
+  )
+}
+```
+
+**The same composed UI works with both:**
+
+```tsx
+// Works with ForwardMessageProvider (local state)
+<ForwardMessageProvider>
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ForwardMessageProvider>
+
+// Works with ChannelProvider (global synced state)
+<ChannelProvider channelId="abc">
+  <Composer.Frame>
+    <Composer.Input />
+    <Composer.Submit />
+  </Composer.Frame>
+</ChannelProvider>
+```
+
+**Custom UI outside the component can access state and actions:**
+
+The provider boundary is what matters—not the visual nesting. Components that
+need shared state don't have to be inside the `Composer.Frame`. They just need
+to be within the provider.
+
+```tsx
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        {/* The composer UI */}
+        <Composer.Frame>
+          <Composer.Input placeholder="Add a message, if you'd like." />
+          <Composer.Footer>
+            <Composer.Formatting />
+            <Composer.Emojis />
+          </Composer.Footer>
+        </Composer.Frame>
+
+        {/* Custom UI OUTSIDE the composer, but INSIDE the provider */}
+        <MessagePreview />
+
+        {/* Actions at the bottom of the dialog */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton />
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+// This button lives OUTSIDE Composer.Frame but can still submit based on its context!
+function ForwardButton() {
+  const {
+    actions: { submit },
+  } = use(ComposerContext)
+  return <Button onPress={submit}>Forward</Button>
+}
+
+// This preview lives OUTSIDE Composer.Frame but can read composer's state!
+function MessagePreview() {
+  const { state } = use(ComposerContext)
+  return <Preview message={state.input} attachments={state.attachments} />
+}
+```
+
+The `ForwardButton` and `MessagePreview` are not visually inside the composer
+box, but they can still access its state and actions. This is the power of
+lifting state into providers.
+
+The UI is reusable bits you compose together. The state is dependency-injected
+by the provider. Swap the provider, keep the UI.
diff --git a/skills/vercel-composition-patterns/rules/state-decouple-implementation.md b/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
new file mode 100644
index 00000000..71a5afaa
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
@@ -0,0 +1,113 @@
+---
+title: Decouple State Management from UI
+impact: MEDIUM
+impactDescription: enables swapping state implementations without changing UI
+tags: composition, state, architecture
+---
+
+## Decouple State Management from UI
+
+The provider component should be the only place that knows how state is managed.
+UI components consume the context interface—they don't know if state comes from
+useState, Zustand, or a server sync.
+
+**Incorrect (UI coupled to state implementation):**
+
+```tsx
+function ChannelComposer({ channelId }: { channelId: string }) {
+  // UI component knows about global state implementation
+  const state = useGlobalChannelState(channelId)
+  const { submit, updateInput } = useChannelSync(channelId)
+
+  return (
+    <Composer.Frame>
+      <Composer.Input
+        value={state.input}
+        onChange={(text) => sync.updateInput(text)}
+      />
+      <Composer.Submit onPress={() => sync.submit()} />
+    </Composer.Frame>
+  )
+}
+```
+
+**Correct (state management isolated in provider):**
+
+```tsx
+// Provider handles all state management details
+function ChannelProvider({
+  channelId,
+  children,
+}: {
+  channelId: string
+  children: React.ReactNode
+}) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update, submit }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// UI component only knows about the context interface
+function ChannelComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Header />
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  )
+}
+
+// Usage
+function Channel({ channelId }: { channelId: string }) {
+  return (
+    <ChannelProvider channelId={channelId}>
+      <ChannelComposer />
+    </ChannelProvider>
+  )
+}
+```
+
+**Different providers, same UI:**
+
+```tsx
+// Local state for ephemeral forms
+function ForwardMessageProvider({ children }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+// Global synced state for channels
+function ChannelProvider({ channelId, children }) {
+  const { state, update, submit } = useGlobalChannel(channelId)
+
+  return (
+    <Composer.Provider state={state} actions={{ update, submit }}>
+      {children}
+    </Composer.Provider>
+  )
+}
+```
+
+The same `Composer.Input` component works with both providers because it only
+depends on the context interface, not the implementation.
diff --git a/skills/vercel-composition-patterns/rules/state-lift-state.md b/skills/vercel-composition-patterns/rules/state-lift-state.md
new file mode 100644
index 00000000..d7fe27b5
--- /dev/null
+++ b/skills/vercel-composition-patterns/rules/state-lift-state.md
@@ -0,0 +1,125 @@
+---
+title: Lift State into Provider Components
+impact: HIGH
+impactDescription: enables state sharing outside component boundaries
+tags: composition, state, context, providers
+---
+
+## Lift State into Provider Components
+
+Move state management into dedicated provider components. This allows sibling
+components outside the main UI to access and modify state without prop drilling
+or awkward refs.
+
+**Incorrect (state trapped inside component):**
+
+```tsx
+function ForwardMessageComposer() {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer />
+    </Composer.Frame>
+  )
+}
+
+// Problem: How does this button access composer state?
+function ForwardMessageDialog() {
+  return (
+    <Dialog>
+      <ForwardMessageComposer />
+      <MessagePreview /> {/* Needs composer state */}
+      <DialogActions>
+        <CancelButton />
+        <ForwardButton /> {/* Needs to call submit */}
+      </DialogActions>
+    </Dialog>
+  )
+}
+```
+
+**Incorrect (useEffect to sync state up):**
+
+```tsx
+function ForwardMessageDialog() {
+  const [input, setInput] = useState('')
+  return (
+    <Dialog>
+      <ForwardMessageComposer onInputChange={setInput} />
+      <MessagePreview input={input} />
+    </Dialog>
+  )
+}
+
+function ForwardMessageComposer({ onInputChange }) {
+  const [state, setState] = useState(initialState)
+  useEffect(() => {
+    onInputChange(state.input) // Sync on every change 😬
+  }, [state.input])
+}
+```
+
+**Incorrect (reading state from ref on submit):**
+
+```tsx
+function ForwardMessageDialog() {
+  const stateRef = useRef(null)
+  return (
+    <Dialog>
+      <ForwardMessageComposer stateRef={stateRef} />
+      <ForwardButton onPress={() => submit(stateRef.current)} />
+    </Dialog>
+  )
+}
+```
+
+**Correct (state lifted to provider):**
+
+```tsx
+function ForwardMessageProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState)
+  const forwardMessage = useForwardMessage()
+  const inputRef = useRef(null)
+
+  return (
+    <Composer.Provider
+      state={state}
+      actions={{ update: setState, submit: forwardMessage }}
+      meta={{ inputRef }}
+    >
+      {children}
+    </Composer.Provider>
+  )
+}
+
+function ForwardMessageDialog() {
+  return (
+    <ForwardMessageProvider>
+      <Dialog>
+        <ForwardMessageComposer />
+        <MessagePreview /> {/* Custom components can access state and actions */}
+        <DialogActions>
+          <CancelButton />
+          <ForwardButton /> {/* Custom components can access state and actions */}
+        </DialogActions>
+      </Dialog>
+    </ForwardMessageProvider>
+  )
+}
+
+function ForwardButton() {
+  const { actions } = use(Composer.Context)
+  return <Button onPress={actions.submit}>Forward</Button>
+}
+```
+
+The ForwardButton lives outside the Composer.Frame but still has access to the
+submit action because it's within the provider. Even though it's a one-off
+component, it can still access the composer's state and actions from outside the
+UI itself.
+
+**Key insight:** Components that need shared state don't have to be visually
+nested inside each other—they just need to be within the same provider.
diff --git a/skills/vercel-react-best-practices/AGENTS.md b/skills/vercel-react-best-practices/AGENTS.md
new file mode 100644
index 00000000..4e340a50
--- /dev/null
+++ b/skills/vercel-react-best-practices/AGENTS.md
@@ -0,0 +1,3810 @@
+# React Best Practices
+
+**Version 1.0.0**  
+Vercel Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React and Next.js codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Eliminating Waterfalls](#1-eliminating-waterfalls) — **CRITICAL**
+   - 1.1 [Check Cheap Conditions Before Async Flags](#11-check-cheap-conditions-before-async-flags)
+   - 1.2 [Defer Await Until Needed](#12-defer-await-until-needed)
+   - 1.3 [Dependency-Based Parallelization](#13-dependency-based-parallelization)
+   - 1.4 [Prevent Waterfall Chains in API Routes](#14-prevent-waterfall-chains-in-api-routes)
+   - 1.5 [Promise.all() for Independent Operations](#15-promiseall-for-independent-operations)
+   - 1.6 [Strategic Suspense Boundaries](#16-strategic-suspense-boundaries)
+2. [Bundle Size Optimization](#2-bundle-size-optimization) — **CRITICAL**
+   - 2.1 [Avoid Barrel File Imports](#21-avoid-barrel-file-imports)
+   - 2.2 [Conditional Module Loading](#22-conditional-module-loading)
+   - 2.3 [Defer Non-Critical Third-Party Libraries](#23-defer-non-critical-third-party-libraries)
+   - 2.4 [Dynamic Imports for Heavy Components](#24-dynamic-imports-for-heavy-components)
+   - 2.5 [Prefer Statically Analyzable Paths](#25-prefer-statically-analyzable-paths)
+   - 2.6 [Preload Based on User Intent](#26-preload-based-on-user-intent)
+3. [Server-Side Performance](#3-server-side-performance) — **HIGH**
+   - 3.1 [Authenticate Server Actions Like API Routes](#31-authenticate-server-actions-like-api-routes)
+   - 3.2 [Avoid Duplicate Serialization in RSC Props](#32-avoid-duplicate-serialization-in-rsc-props)
+   - 3.3 [Avoid Shared Module State for Request Data](#33-avoid-shared-module-state-for-request-data)
+   - 3.4 [Cross-Request LRU Caching](#34-cross-request-lru-caching)
+   - 3.5 [Hoist Static I/O to Module Level](#35-hoist-static-io-to-module-level)
+   - 3.6 [Minimize Serialization at RSC Boundaries](#36-minimize-serialization-at-rsc-boundaries)
+   - 3.7 [Parallel Data Fetching with Component Composition](#37-parallel-data-fetching-with-component-composition)
+   - 3.8 [Parallel Nested Data Fetching](#38-parallel-nested-data-fetching)
+   - 3.9 [Per-Request Deduplication with React.cache()](#39-per-request-deduplication-with-reactcache)
+   - 3.10 [Use after() for Non-Blocking Operations](#310-use-after-for-non-blocking-operations)
+4. [Client-Side Data Fetching](#4-client-side-data-fetching) — **MEDIUM-HIGH**
+   - 4.1 [Deduplicate Global Event Listeners](#41-deduplicate-global-event-listeners)
+   - 4.2 [Use Passive Event Listeners for Scrolling Performance](#42-use-passive-event-listeners-for-scrolling-performance)
+   - 4.3 [Use SWR for Automatic Deduplication](#43-use-swr-for-automatic-deduplication)
+   - 4.4 [Version and Minimize localStorage Data](#44-version-and-minimize-localstorage-data)
+5. [Re-render Optimization](#5-re-render-optimization) — **MEDIUM**
+   - 5.1 [Calculate Derived State During Rendering](#51-calculate-derived-state-during-rendering)
+   - 5.2 [Defer State Reads to Usage Point](#52-defer-state-reads-to-usage-point)
+   - 5.3 [Do not wrap a simple expression with a primitive result type in useMemo](#53-do-not-wrap-a-simple-expression-with-a-primitive-result-type-in-usememo)
+   - 5.4 [Don't Define Components Inside Components](#54-dont-define-components-inside-components)
+   - 5.5 [Extract Default Non-primitive Parameter Value from Memoized Component to Constant](#55-extract-default-non-primitive-parameter-value-from-memoized-component-to-constant)
+   - 5.6 [Extract to Memoized Components](#56-extract-to-memoized-components)
+   - 5.7 [Narrow Effect Dependencies](#57-narrow-effect-dependencies)
+   - 5.8 [Put Interaction Logic in Event Handlers](#58-put-interaction-logic-in-event-handlers)
+   - 5.9 [Split Combined Hook Computations](#59-split-combined-hook-computations)
+   - 5.10 [Subscribe to Derived State](#510-subscribe-to-derived-state)
+   - 5.11 [Use Functional setState Updates](#511-use-functional-setstate-updates)
+   - 5.12 [Use Lazy State Initialization](#512-use-lazy-state-initialization)
+   - 5.13 [Use Transitions for Non-Urgent Updates](#513-use-transitions-for-non-urgent-updates)
+   - 5.14 [Use useDeferredValue for Expensive Derived Renders](#514-use-usedeferredvalue-for-expensive-derived-renders)
+   - 5.15 [Use useRef for Transient Values](#515-use-useref-for-transient-values)
+6. [Rendering Performance](#6-rendering-performance) — **MEDIUM**
+   - 6.1 [Animate SVG Wrapper Instead of SVG Element](#61-animate-svg-wrapper-instead-of-svg-element)
+   - 6.2 [CSS content-visibility for Long Lists](#62-css-content-visibility-for-long-lists)
+   - 6.3 [Hoist Static JSX Elements](#63-hoist-static-jsx-elements)
+   - 6.4 [Optimize SVG Precision](#64-optimize-svg-precision)
+   - 6.5 [Prevent Hydration Mismatch Without Flickering](#65-prevent-hydration-mismatch-without-flickering)
+   - 6.6 [Suppress Expected Hydration Mismatches](#66-suppress-expected-hydration-mismatches)
+   - 6.7 [Use Activity Component for Show/Hide](#67-use-activity-component-for-showhide)
+   - 6.8 [Use defer or async on Script Tags](#68-use-defer-or-async-on-script-tags)
+   - 6.9 [Use Explicit Conditional Rendering](#69-use-explicit-conditional-rendering)
+   - 6.10 [Use React DOM Resource Hints](#610-use-react-dom-resource-hints)
+   - 6.11 [Use useTransition Over Manual Loading States](#611-use-usetransition-over-manual-loading-states)
+7. [JavaScript Performance](#7-javascript-performance) — **LOW-MEDIUM**
+   - 7.1 [Avoid Layout Thrashing](#71-avoid-layout-thrashing)
+   - 7.2 [Build Index Maps for Repeated Lookups](#72-build-index-maps-for-repeated-lookups)
+   - 7.3 [Cache Property Access in Loops](#73-cache-property-access-in-loops)
+   - 7.4 [Cache Repeated Function Calls](#74-cache-repeated-function-calls)
+   - 7.5 [Cache Storage API Calls](#75-cache-storage-api-calls)
+   - 7.6 [Combine Multiple Array Iterations](#76-combine-multiple-array-iterations)
+   - 7.7 [Defer Non-Critical Work with requestIdleCallback](#77-defer-non-critical-work-with-requestidlecallback)
+   - 7.8 [Early Length Check for Array Comparisons](#78-early-length-check-for-array-comparisons)
+   - 7.9 [Early Return from Functions](#79-early-return-from-functions)
+   - 7.10 [Hoist RegExp Creation](#710-hoist-regexp-creation)
+   - 7.11 [Use flatMap to Map and Filter in One Pass](#711-use-flatmap-to-map-and-filter-in-one-pass)
+   - 7.12 [Use Loop for Min/Max Instead of Sort](#712-use-loop-for-minmax-instead-of-sort)
+   - 7.13 [Use Set/Map for O(1) Lookups](#713-use-setmap-for-o1-lookups)
+   - 7.14 [Use toSorted() Instead of sort() for Immutability](#714-use-tosorted-instead-of-sort-for-immutability)
+8. [Advanced Patterns](#8-advanced-patterns) — **LOW**
+   - 8.1 [Do Not Put Effect Events in Dependency Arrays](#81-do-not-put-effect-events-in-dependency-arrays)
+   - 8.2 [Initialize App Once, Not Per Mount](#82-initialize-app-once-not-per-mount)
+   - 8.3 [Store Event Handlers in Refs](#83-store-event-handlers-in-refs)
+   - 8.4 [useEffectEvent for Stable Callback Refs](#84-useeffectevent-for-stable-callback-refs)
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL**
+
+Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+### 1.1 Check Cheap Conditions Before Async Flags
+
+**Impact: HIGH (avoids unnecessary async work when a synchronous guard already fails)**
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
+
+### 1.2 Defer Await Until Needed
+
+**Impact: HIGH (avoids blocking unused code paths)**
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect: blocks both branches**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct: only blocks when needed**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example: early return optimization**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
+
+### 1.3 Dependency-Based Parallelization
+
+**Impact: CRITICAL (2-10× improvement)**
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect: profile waits for config unnecessarily**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct: config and profile run in parallel**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+
+### 1.4 Prevent Waterfall Chains in API Routes
+
+**Impact: CRITICAL (2-10× improvement)**
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect: config waits for auth, data waits for both**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct: auth and config start immediately**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
+
+### 1.5 Promise.all() for Independent Operations
+
+**Impact: CRITICAL (2-10× improvement)**
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect: sequential execution, 3 round trips**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct: parallel execution, 1 round trip**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.6 Strategic Suspense Boundaries
+
+**Impact: HIGH (faster initial paint)**
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect: wrapper blocked by data fetching**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct: wrapper shows immediately, data streams in**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative: share promise across components**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+
+- SEO-critical content above the fold
+
+- Small, fast queries where suspense overhead isn't worth it
+
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL**
+
+Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+### 2.1 Avoid Barrel File Imports
+
+**Impact: CRITICAL (200-800ms import cost, slow builds)**
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect: imports entire library**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+
+### 2.2 Conditional Module Loading
+
+**Impact: HIGH (loads large data only when needed)**
+
+Load large data or modules only when a feature is activated.
+
+**Example: lazy-load animation frames**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
+
+### 2.3 Defer Non-Critical Third-Party Libraries
+
+**Impact: MEDIUM (loads after hydration)**
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect: blocks initial bundle**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct: loads after hydration**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+### 2.4 Dynamic Imports for Heavy Components
+
+**Impact: CRITICAL (directly affects TTI and LCP)**
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect: Monaco bundles with main chunk ~300KB**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct: Monaco loads on demand**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+### 2.5 Prefer Statically Analyzable Paths
+
+**Impact: HIGH (avoids accidental broad bundles and file traces)**
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+
+- Larger server bundles
+
+- Slower builds
+
+- Worse cold starts
+
+- More memory use
+
+**Incorrect: the bundler cannot tell what may be imported**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct: use an explicit map of allowed modules**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+**Incorrect: a 2-value enum still hides the final path from static analysis**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct: make each final path literal at the callsite**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [https://nextjs.org/docs/app/api-reference/config/next-config-js/output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [https://nextjs.org/learn/seo/dynamic-imports](https://nextjs.org/learn/seo/dynamic-imports), [https://vite.dev/guide/features.html](https://vite.dev/guide/features.html), [https://esbuild.github.io/api/](https://esbuild.github.io/api/), [https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [https://webpack.js.org/guides/dependency-management/](https://webpack.js.org/guides/dependency-management/)
+
+### 2.6 Preload Based on User Intent
+
+**Impact: MEDIUM (reduces perceived latency)**
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example: preload on hover/focus**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example: preload when feature flag is enabled**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+### 3.1 Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect: no authentication check**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct: authentication inside the action**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
+
+### 3.2 Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect: duplicates array**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct: sends 3 strings**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+**Operations breaking deduplication: create new references**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
+
+### 3.3 Avoid Shared Module State for Request Data
+
+**Impact: HIGH (prevents concurrency bugs and request data leaks)**
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect: request data leaks across concurrent renders**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct: keep request data local to the render tree**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
+
+### 3.4 Cross-Request LRU Caching
+
+**Impact: HIGH (caches across requests)**
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+
+### 3.5 Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect: reads font file on every request**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct: loads once at module initialization**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct: synchronous fs at module level**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect: reads config on every call**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct: hoists config and template to module level**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+
+- Loading static logos, icons, or watermarks
+
+- Reading configuration files that don't change at runtime
+
+- Loading email templates or other static templates
+
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+
+- Files that may change during runtime (use caching with TTL instead)
+
+- Large files that would consume too much memory if kept loaded
+
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
+
+### 3.6 Minimize Serialization at RSC Boundaries
+
+**Impact: HIGH (reduces data transfer size)**
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect: serializes all 50 fields**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct: serializes only 1 field**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
+
+### 3.7 Parallel Data Fetching with Component Composition
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect: Sidebar waits for Page's fetch to complete**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct: both fetch simultaneously**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
+
+### 3.8 Parallel Nested Data Fetching
+
+**Impact: CRITICAL (eliminates server-side waterfalls)**
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect: a single slow item blocks all nested fetches**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct: each item chains its own nested fetch**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
+
+### 3.9 Per-Request Deduplication with React.cache()
+
+**Impact: MEDIUM (deduplicates within request)**
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect: always cache miss**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct: cache hit**
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+If you must pass objects, pass the same reference:
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+
+- Heavy computations
+
+- Authentication checks
+
+- File system operations
+
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [https://react.dev/reference/react/cache](https://react.dev/reference/react/cache)
+
+### 3.10 Use after() for Non-Blocking Operations
+
+**Impact: MEDIUM (faster response times)**
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect: blocks response**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+
+- Audit logging
+
+- Sending notifications
+
+- Cache invalidation
+
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+### 4.1 Deduplicate Global Event Listeners
+
+**Impact: LOW (single listener for N components)**
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect: N instances = N listeners**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct: N instances = 1 listener**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
+
+### 4.2 Use Passive Event Listeners for Scrolling Performance
+
+**Impact: MEDIUM (eliminates scroll delay caused by event listeners)**
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
+
+### 4.3 Use SWR for Automatic Deduplication
+
+**Impact: MEDIUM-HIGH (automatic deduplication)**
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect: no deduplication, each instance fetches**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct: multiple instances share one request**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
+
+### 4.4 Version and Minimize localStorage Data
+
+**Impact: MEDIUM (prevents schema conflicts, reduces storage size)**
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+### 5.1 Calculate Derived State During Rendering
+
+**Impact: MEDIUM (avoids redundant renders and state drift)**
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect: redundant state and effect**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct: derive during render**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect](https://react.dev/learn/you-might-not-need-an-effect)
+
+### 5.2 Defer State Reads to Usage Point
+
+**Impact: MEDIUM (avoids unnecessary subscriptions)**
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect: subscribes to all searchParams changes**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct: reads on demand, no subscription**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+### 5.3 Do not wrap a simple expression with a primitive result type in useMemo
+
+**Impact: LOW-MEDIUM (wasted computation on every render)**
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+### 5.4 Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect: remounts on every render**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct: pass props instead**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+
+- Input fields lose focus on every keystroke
+
+- Animations restart unexpectedly
+
+- `useEffect` cleanup/setup runs on every parent render
+
+- Scroll position resets inside the component
+
+### 5.5 Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+**Impact: MEDIUM (restores memoization by using a constant for default value)**
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect: `onClick` has different values on every rerender**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct: stable default value**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+### 5.6 Extract to Memoized Components
+
+**Impact: MEDIUM (enables early returns)**
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect: computes avatar even when loading**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct: skips computation when loading**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
+
+### 5.7 Narrow Effect Dependencies
+
+**Impact: LOW (minimizes effect re-runs)**
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect: re-runs on any user field change**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct: re-runs only when id changes**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
+
+### 5.8 Put Interaction Logic in Event Handlers
+
+**Impact: MEDIUM (avoids effect re-runs and duplicate side effects)**
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect: event modeled as state + effect**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct: do it in the handler**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
+
+### 5.9 Split Combined Hook Computations
+
+**Impact: MEDIUM (avoids recomputing independent steps)**
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect: changing `sortOrder` recomputes filtering**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct: filtering only recomputes when products or category change**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect: both effects run when either dependency changes**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct: effects run independently**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
+
+### 5.10 Subscribe to Derived State
+
+**Impact: MEDIUM (reduces re-render frequency)**
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect: re-renders on every pixel change**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct: re-renders only when boolean changes**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+### 5.11 Use Functional setState Updates
+
+**Impact: MEDIUM (prevents stale closures and unnecessary callback recreations)**
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect: requires state as dependency**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct: stable callbacks, no stale closures**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+
+2. **No stale closures** - Always operates on the latest state value
+
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+
+- Inside useCallback/useMemo when state is needed
+
+- Event handlers that reference state
+
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+
+- Setting state from props/arguments only: `setName(newName)`
+
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
+
+### 5.12 Use Lazy State Initialization
+
+**Impact: MEDIUM (wasted computation on every render)**
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect: runs on every render**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct: runs only once**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
+
+### 5.13 Use Transitions for Non-Urgent Updates
+
+**Impact: MEDIUM (maintains UI responsiveness)**
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect: blocks UI on every scroll**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct: non-blocking updates**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+### 5.14 Use useDeferredValue for Expensive Derived Renders
+
+**Impact: MEDIUM (keeps input responsive during heavy computation)**
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect: input feels laggy while filtering**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct: input stays snappy, results render when ready**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+
+- Expensive visualizations (charts, graphs) reacting to input
+
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [https://react.dev/reference/react/useDeferredValue](https://react.dev/reference/react/useDeferredValue)
+
+### 5.15 Use useRef for Transient Values
+
+**Impact: MEDIUM (avoids unnecessary re-renders on frequent updates)**
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect: renders every update**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct: no re-render for tracking**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+Optimizing the rendering process reduces the work the browser needs to do.
+
+### 6.1 Animate SVG Wrapper Instead of SVG Element
+
+**Impact: LOW (enables hardware acceleration)**
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect: animating SVG directly - no hardware acceleration**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct: animating wrapper div - hardware accelerated**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
+
+### 6.2 CSS content-visibility for Long Lists
+
+**Impact: HIGH (faster initial render)**
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
+
+### 6.3 Hoist Static JSX Elements
+
+**Impact: LOW (avoids re-creation)**
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect: recreates element every render**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct: reuses same element**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
+
+### 6.4 Optimize SVG Precision
+
+**Impact: LOW (reduces file size)**
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect: excessive precision**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct: 1 decimal place**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
+
+### 6.5 Prevent Hydration Mismatch Without Flickering
+
+**Impact: MEDIUM (avoids visual flicker and hydration errors)**
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect: breaks SSR**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect: visual flickering**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct: no flicker, no hydration mismatch**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
+
+### 6.6 Suppress Expected Hydration Mismatches
+
+**Impact: LOW-MEDIUM (avoids noisy hydration warnings for known differences)**
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect: known mismatch warnings**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct: suppress expected mismatch only**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
+
+### 6.7 Use Activity Component for Show/Hide
+
+**Impact: MEDIUM (preserves state/DOM)**
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
+
+### 6.8 Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect: blocks rendering**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct: non-blocking**
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+Reference: [https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
+
+### 6.9 Use Explicit Conditional Rendering
+
+**Impact: LOW (prevents rendering 0 or NaN)**
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect: renders "0" when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct: renders nothing when count is 0**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+### 6.10 Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example: preconnect to third-party APIs**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example: preload critical fonts and styles**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example: preload modules for code-split routes**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+
+|-----|----------|
+
+| `prefetchDNS` | Third-party domains you'll connect to later |
+
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+
+| `preload` | Critical resources needed for current page |
+
+| `preloadModule` | JS modules for likely next navigation |
+
+| `preinit` | Stylesheets/scripts that must execute early |
+
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [https://react.dev/reference/react-dom#resource-preloading-apis](https://react.dev/reference/react-dom#resource-preloading-apis)
+
+### 6.11 Use useTransition Over Manual Loading States
+
+**Impact: LOW (reduces re-renders and improves code clarity)**
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect: manual loading state**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct: useTransition with built-in pending state**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+
+- **Error resilience**: Pending state correctly resets even if the transition throws
+
+- **Better responsiveness**: Keeps the UI responsive during updates
+
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [https://react.dev/reference/react/useTransition](https://react.dev/reference/react/useTransition)
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+Micro-optimizations for hot paths can add up to meaningful improvements.
+
+### 7.1 Avoid Layout Thrashing
+
+**Impact: MEDIUM (prevents forced synchronous layouts and reduces performance bottlenecks)**
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK: browser batches style changes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect: interleaved reads and writes force reflows**
+
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct: batch writes, then read once**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct: batch reads, then writes**
+
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Better: use CSS classes**
+
+**React example:**
+
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
+
+### 7.2 Build Index Maps for Repeated Lookups
+
+**Impact: LOW-MEDIUM (1M ops to 2K ops)**
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+
+For 1000 orders × 1000 users: 1M ops → 2K ops.
+
+### 7.3 Cache Property Access in Loops
+
+**Impact: LOW-MEDIUM (reduces lookups)**
+
+Cache object property lookups in hot paths.
+
+**Incorrect: 3 lookups × N iterations**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct: 1 lookup total**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
+
+### 7.4 Cache Repeated Function Calls
+
+**Impact: MEDIUM (avoid redundant computation)**
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect: redundant computation**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct: cached results**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
+
+### 7.5 Cache Storage API Calls
+
+**Impact: LOW-MEDIUM (reduces expensive I/O)**
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect: reads storage on every call**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct: Map cache**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important: invalidate on external changes**
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+### 7.6 Combine Multiple Array Iterations
+
+**Impact: LOW-MEDIUM (reduces iterations)**
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect: 3 iterations**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct: 1 iteration**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
+
+### 7.7 Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect: blocks main thread during user interaction**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct: defers non-critical work to idle time**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+
+- Saving state to localStorage/IndexedDB
+
+- Prefetching resources for likely next actions
+
+- Processing non-urgent data transformations
+
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+
+- Rendering updates the user is waiting for
+
+- Time-sensitive operations
+
+### 7.8 Early Length Check for Array Comparisons
+
+**Impact: MEDIUM-HIGH (avoids expensive operations when lengths differ)**
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect: always runs expensive comparison**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+
+- It avoids mutating the original arrays
+
+- It returns early when a difference is found
+
+### 7.9 Early Return from Functions
+
+**Impact: LOW-MEDIUM (avoids unnecessary computation)**
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect: processes all items even after finding answer**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct: returns immediately on first error**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
+
+### 7.10 Hoist RegExp Creation
+
+**Impact: LOW-MEDIUM (avoids recreation)**
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect: new RegExp every render**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct: memoize or hoist**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning: global regex has mutable state**
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+### 7.11 Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect: 2 iterations, intermediate array**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct: 1 iteration, no intermediate array**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+
+- Transforming items while filtering some out
+
+- Conditional mapping where some inputs produce no output
+
+- Parsing/validating where invalid inputs should be skipped
+
+### 7.12 Use Loop for Min/Max Instead of Sort
+
+**Impact: LOW (O(n) instead of O(n log n))**
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative: Math.min/Math.max for small arrays**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
+
+### 7.13 Use Set/Map for O(1) Lookups
+
+**Impact: LOW-MEDIUM (O(n) to O(1))**
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
+
+### 7.14 Use toSorted() Instead of sort() for Immutability
+
+**Impact: MEDIUM-HIGH (prevents mutation bugs in React state)**
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect: mutates original array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct: creates new array**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support: fallback for older browsers**
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+
+- `.toReversed()` - immutable reverse
+
+- `.toSpliced()` - immutable splice
+
+- `.with()` - immutable element replacement
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+Advanced patterns for specific cases that require careful implementation.
+
+### 8.1 Do Not Put Effect Events in Dependency Arrays
+
+**Impact: LOW (avoids unnecessary effect re-runs and lint errors)**
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect: Effect Event added as a dependency**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct: depend on reactive values, not the Effect Event**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [https://react.dev/reference/react/useEffectEvent#effect-event-in-deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
+
+### 8.2 Initialize App Once, Not Per Mount
+
+**Impact: LOW-MEDIUM (avoids duplicate init in development)**
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect: runs twice in dev, re-runs on remount**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct: once per app load**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+### 8.3 Store Event Handlers in Refs
+
+**Impact: LOW (stable subscriptions)**
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect: re-subscribes on every render**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct: stable subscription**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+### 8.4 useEffectEvent for Stable Callback Refs
+
+**Impact: LOW (prevents effect re-runs)**
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect: effect re-runs on every callback change**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct: using React's useEffectEvent**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://nextjs.org](https://nextjs.org)
+3. [https://swr.vercel.app](https://swr.vercel.app)
+4. [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
+5. [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
+6. [https://vercel.com/blog/how-we-optimized-package-imports-in-next-js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+7. [https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel-react-best-practices/README.md b/skills/vercel-react-best-practices/README.md
new file mode 100644
index 00000000..f283e1c0
--- /dev/null
+++ b/skills/vercel-react-best-practices/README.md
@@ -0,0 +1,123 @@
+# React Best Practices
+
+A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `src/` - Build scripts and utilities
+- `metadata.json` - Document metadata (version, organization, abstract)
+- __`AGENTS.md`__ - Compiled output (generated)
+- __`test-cases.json`__ - Test cases for LLM evaluation (generated)
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+
+2. Build AGENTS.md from rules:
+   ```bash
+   pnpm build
+   ```
+
+3. Validate rule files:
+   ```bash
+   pnpm validate
+   ```
+
+4. Extract test cases:
+   ```bash
+   pnpm extract-tests
+   ```
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `async-` for Eliminating Waterfalls (Section 1)
+   - `bundle-` for Bundle Size Optimization (Section 2)
+   - `server-` for Server-Side Performance (Section 3)
+   - `client-` for Client-Side Data Fetching (Section 4)
+   - `rerender-` for Re-render Optimization (Section 5)
+   - `rendering-` for Rendering Performance (Section 6)
+   - `js-` for JavaScript Performance (Section 7)
+   - `advanced-` for Advanced Patterns (Section 8)
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+```markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example
+```
+
+Optional explanatory text after examples.
+
+Reference: [Link](https://example.com)
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `async-parallel.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+- IDs (e.g., 1.1, 1.2) are auto-generated during build
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, major performance gains
+- `HIGH` - Significant performance improvements
+- `MEDIUM-HIGH` - Moderate-high gains
+- `MEDIUM` - Moderate performance improvements
+- `LOW-MEDIUM` - Low-medium gains
+- `LOW` - Incremental improvements
+
+## Scripts
+
+- `pnpm build` - Compile rules into AGENTS.md
+- `pnpm validate` - Validate all rule files
+- `pnpm extract-tests` - Extract test cases for LLM evaluation
+- `pnpm dev` - Build and validate
+
+## Contributing
+
+When adding or modifying rules:
+
+1. Use the correct filename prefix for your section
+2. Follow the `_template.md` structure
+3. Include clear bad/good examples with explanations
+4. Add appropriate tags
+5. Run `pnpm build` to regenerate AGENTS.md and test-cases.json
+6. Rules are automatically sorted by title - no need to manage numbers!
+
+## Acknowledgments
+
+Originally created by [@shuding](https://x.com/shuding) at [Vercel](https://vercel.com).
diff --git a/skills/vercel-react-best-practices/SKILL.md b/skills/vercel-react-best-practices/SKILL.md
new file mode 100644
index 00000000..237988de
--- /dev/null
+++ b/skills/vercel-react-best-practices/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: vercel-react-best-practices
+description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# Vercel React Best Practices
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new React components or Next.js pages
+- Implementing data fetching (client or server-side)
+- Reviewing code for performance issues
+- Refactoring existing React/Next.js code
+- Optimizing bundle size or load times
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values
+- `async-defer-await` - Move await into branches where actually used
+- `async-parallel` - Use Promise.all() for independent operations
+- `async-dependencies` - Use better-all for partial dependencies
+- `async-api-routes` - Start promises early, await late in API routes
+- `async-suspense-boundaries` - Use Suspense to stream content
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly, avoid barrel files
+- `bundle-analyzable-paths` - Prefer statically analyzable import and file-system paths to avoid broad bundles and traces
+- `bundle-dynamic-imports` - Use next/dynamic for heavy components
+- `bundle-defer-third-party` - Load analytics/logging after hydration
+- `bundle-conditional` - Load modules only when feature is activated
+- `bundle-preload` - Preload on hover/focus for perceived speed
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Authenticate server actions like API routes
+- `server-cache-react` - Use React.cache() for per-request deduplication
+- `server-cache-lru` - Use LRU cache for cross-request caching
+- `server-dedup-props` - Avoid duplicate serialization in RSC props
+- `server-hoist-static-io` - Hoist static I/O (fonts, logos) to module level
+- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR
+- `server-serialization` - Minimize data passed to client components
+- `server-parallel-fetching` - Restructure components to parallelize fetches
+- `server-parallel-nested-fetching` - Chain nested fetches per item in Promise.all
+- `server-after-nonblocking` - Use after() for non-blocking operations
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR for automatic request deduplication
+- `client-event-listeners` - Deduplicate global event listeners
+- `client-passive-event-listeners` - Use passive listeners for scroll
+- `client-localstorage-schema` - Version and minimize localStorage data
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
+- `rerender-memo` - Extract expensive work into memoized components
+- `rerender-memo-with-default-value` - Hoist default non-primitive props
+- `rerender-dependencies` - Use primitive dependencies in effects
+- `rerender-derived-state` - Subscribe to derived booleans, not raw values
+- `rerender-derived-state-no-effect` - Derive state during render, not effects
+- `rerender-functional-setstate` - Use functional setState for stable callbacks
+- `rerender-lazy-state-init` - Pass function to useState for expensive values
+- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
+- `rerender-split-combined-hooks` - Split hooks with independent dependencies
+- `rerender-move-effect-to-event` - Put interaction logic in event handlers
+- `rerender-transitions` - Use startTransition for non-urgent updates
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive
+- `rerender-use-ref-transient-values` - Use refs for transient frequent values
+- `rerender-no-inline-components` - Don't define components inside components
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
+- `rendering-content-visibility` - Use content-visibility for long lists
+- `rendering-hoist-jsx` - Extract static JSX outside components
+- `rendering-svg-precision` - Reduce SVG coordinate precision
+- `rendering-hydration-no-flicker` - Use inline script for client-only data
+- `rendering-hydration-suppress-warning` - Suppress expected mismatches
+- `rendering-activity` - Use Activity component for show/hide
+- `rendering-conditional-render` - Use ternary, not && for conditionals
+- `rendering-usetransition-loading` - Prefer useTransition for loading state
+- `rendering-resource-hints` - Use React DOM resource hints for preloading
+- `rendering-script-defer-async` - Use defer or async on script tags
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-batch-dom-css` - Group CSS changes via classes or cssText
+- `js-index-maps` - Build Map for repeated lookups
+- `js-cache-property-access` - Cache object properties in loops
+- `js-cache-function-results` - Cache function results in module-level Map
+- `js-cache-storage` - Cache localStorage/sessionStorage reads
+- `js-combine-iterations` - Combine multiple filter/map into one loop
+- `js-length-check-first` - Check array length before expensive comparison
+- `js-early-exit` - Return early from functions
+- `js-hoist-regexp` - Hoist RegExp creation outside loops
+- `js-min-max-loop` - Use loop for min/max instead of sort
+- `js-set-map-lookups` - Use Set/Map for O(1) lookups
+- `js-tosorted-immutable` - Use toSorted() for immutability
+- `js-flatmap-filter` - Use flatMap to map and filter in one pass
+- `js-request-idle-callback` - Defer non-critical work to browser idle time
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps
+- `advanced-event-handler-refs` - Store event handlers in refs
+- `advanced-init-once` - Initialize app once per app load
+- `advanced-use-latest` - useLatest for stable callback refs
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/async-parallel.md
+rules/bundle-barrel-imports.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel-react-best-practices/metadata.json b/skills/vercel-react-best-practices/metadata.json
new file mode 100644
index 00000000..3bec38b1
--- /dev/null
+++ b/skills/vercel-react-best-practices/metadata.json
@@ -0,0 +1,15 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React and Next.js applications, designed for AI agents and LLMs. Contains 40+ rules across 8 categories, prioritized by impact from critical (eliminating waterfalls, reducing bundle size) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://nextjs.org",
+    "https://swr.vercel.app",
+    "https://github.com/shuding/better-all",
+    "https://github.com/isaacs/node-lru-cache",
+    "https://vercel.com/blog/how-we-optimized-package-imports-in-next-js",
+    "https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast"
+  ]
+}
diff --git a/skills/vercel-react-best-practices/rules/_sections.md b/skills/vercel-react-best-practices/rules/_sections.md
new file mode 100644
index 00000000..4d20c144
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/_sections.md
@@ -0,0 +1,46 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Eliminating Waterfalls (async)
+
+**Impact:** CRITICAL  
+**Description:** Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.
+
+## 2. Bundle Size Optimization (bundle)
+
+**Impact:** CRITICAL  
+**Description:** Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.
+
+## 3. Server-Side Performance (server)
+
+**Impact:** HIGH  
+**Description:** Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.
+
+## 4. Client-Side Data Fetching (client)
+
+**Impact:** MEDIUM-HIGH  
+**Description:** Automatic deduplication and efficient data fetching patterns reduce redundant network requests.
+
+## 5. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM  
+**Description:** Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.
+
+## 6. Rendering Performance (rendering)
+
+**Impact:** MEDIUM  
+**Description:** Optimizing the rendering process reduces the work the browser needs to do.
+
+## 7. JavaScript Performance (js)
+
+**Impact:** LOW-MEDIUM  
+**Description:** Micro-optimizations for hot paths can add up to meaningful improvements.
+
+## 8. Advanced Patterns (advanced)
+
+**Impact:** LOW  
+**Description:** Advanced patterns for specific cases that require careful implementation.
diff --git a/skills/vercel-react-best-practices/rules/_template.md b/skills/vercel-react-best-practices/rules/_template.md
new file mode 100644
index 00000000..1e9e7070
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md b/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
new file mode 100644
index 00000000..24d901b6
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
@@ -0,0 +1,56 @@
+---
+title: Do Not Put Effect Events in Dependency Arrays
+impact: LOW
+impactDescription: avoids unnecessary effect re-runs and lint errors
+tags: advanced, hooks, useEffectEvent, dependencies, effects
+---
+
+## Do Not Put Effect Events in Dependency Arrays
+
+Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. Do not include the function returned by `useEffectEvent` in a `useEffect` dependency array. Keep the actual reactive values as dependencies and call the Effect Event from inside the effect body or subscriptions created by that effect.
+
+**Incorrect (Effect Event added as a dependency):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId, handleConnected])
+}
+```
+
+Including the Effect Event in dependencies makes the effect re-run every render and triggers the React Hooks lint rule.
+
+**Correct (depend on reactive values, not the Effect Event):**
+
+```tsx
+import { useEffect, useEffectEvent } from 'react'
+
+function ChatRoom({ roomId, onConnected }: {
+  roomId: string
+  onConnected: () => void
+}) {
+  const handleConnected = useEffectEvent(onConnected)
+
+  useEffect(() => {
+    const connection = createConnection(roomId)
+    connection.on('connected', handleConnected)
+    connection.connect()
+
+    return () => connection.disconnect()
+  }, [roomId])
+}
+```
+
+Reference: [React useEffectEvent: Effect Event in deps](https://react.dev/reference/react/useEffectEvent#effect-event-in-deps)
diff --git a/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md b/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
new file mode 100644
index 00000000..97e7ade2
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
diff --git a/skills/vercel-react-best-practices/rules/advanced-init-once.md b/skills/vercel-react-best-practices/rules/advanced-init-once.md
new file mode 100644
index 00000000..73ee38e5
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-init-once.md
@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
diff --git a/skills/vercel-react-best-practices/rules/advanced-use-latest.md b/skills/vercel-react-best-practices/rules/advanced-use-latest.md
new file mode 100644
index 00000000..9c7cb501
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/advanced-use-latest.md
@@ -0,0 +1,39 @@
+---
+title: useEffectEvent for Stable Callback Refs
+impact: LOW
+impactDescription: prevents effect re-runs
+tags: advanced, hooks, useEffectEvent, refs, optimization
+---
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/async-api-routes.md b/skills/vercel-react-best-practices/rules/async-api-routes.md
new file mode 100644
index 00000000..6feda1ef
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-api-routes.md
@@ -0,0 +1,38 @@
+---
+title: Prevent Waterfall Chains in API Routes
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: api-routes, server-actions, waterfalls, parallelization
+---
+
+## Prevent Waterfall Chains in API Routes
+
+In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
+
+**Incorrect (config waits for auth, data waits for both):**
+
+```typescript
+export async function GET(request: Request) {
+  const session = await auth()
+  const config = await fetchConfig()
+  const data = await fetchData(session.user.id)
+  return Response.json({ data, config })
+}
+```
+
+**Correct (auth and config start immediately):**
+
+```typescript
+export async function GET(request: Request) {
+  const sessionPromise = auth()
+  const configPromise = fetchConfig()
+  const session = await sessionPromise
+  const [config, data] = await Promise.all([
+    configPromise,
+    fetchData(session.user.id)
+  ])
+  return Response.json({ data, config })
+}
+```
+
+For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
diff --git a/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md b/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
new file mode 100644
index 00000000..5799d7f6
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
@@ -0,0 +1,37 @@
+---
+title: Check Cheap Conditions Before Async Flags
+impact: HIGH
+impactDescription: avoids unnecessary async work when a synchronous guard already fails
+tags: async, await, feature-flags, short-circuit, conditional
+---
+
+## Check Cheap Conditions Before Async Flags
+
+When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
+
+This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+
+**Incorrect:**
+
+```typescript
+const someFlag = await getFlag()
+
+if (someFlag && someCondition) {
+  // ...
+}
+```
+
+**Correct:**
+
+```typescript
+if (someCondition) {
+  const someFlag = await getFlag()
+  if (someFlag) {
+    // ...
+  }
+}
+```
+
+This matters when `getFlag` hits the network, a feature-flag service, or `React.cache` / DB work: skipping it when `someCondition` is false removes that cost on the cold path.
+
+Keep the original order if `someCondition` is expensive, depends on the flag, or you must run side effects in a fixed order.
diff --git a/skills/vercel-react-best-practices/rules/async-defer-await.md b/skills/vercel-react-best-practices/rules/async-defer-await.md
new file mode 100644
index 00000000..460b5e16
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-defer-await.md
@@ -0,0 +1,82 @@
+---
+title: Defer Await Until Needed
+impact: HIGH
+impactDescription: avoids blocking unused code paths
+tags: async, await, conditional, optimization
+---
+
+## Defer Await Until Needed
+
+Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
+
+**Incorrect (blocks both branches):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  
+  if (skipProcessing) {
+    // Returns immediately but still waited for userData
+    return { skipped: true }
+  }
+  
+  // Only this branch uses userData
+  return processUserData(userData)
+}
+```
+
+**Correct (only blocks when needed):**
+
+```typescript
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) {
+    // Returns immediately without waiting
+    return { skipped: true }
+  }
+  
+  // Fetch only when needed
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+**Another example (early return optimization):**
+
+```typescript
+// Incorrect: always fetches permissions
+async function updateResource(resourceId: string, userId: string) {
+  const permissions = await fetchPermissions(userId)
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+
+// Correct: fetches only when needed
+async function updateResource(resourceId: string, userId: string) {
+  const resource = await getResource(resourceId)
+  
+  if (!resource) {
+    return { error: 'Not found' }
+  }
+  
+  const permissions = await fetchPermissions(userId)
+  
+  if (!permissions.canEdit) {
+    return { error: 'Forbidden' }
+  }
+  
+  return await updateResourceData(resource, permissions)
+}
+```
+
+This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
+
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
diff --git a/skills/vercel-react-best-practices/rules/async-dependencies.md b/skills/vercel-react-best-practices/rules/async-dependencies.md
new file mode 100644
index 00000000..0484ebab
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-dependencies.md
@@ -0,0 +1,51 @@
+---
+title: Dependency-Based Parallelization
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, dependencies, better-all
+---
+
+## Dependency-Based Parallelization
+
+For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
+
+**Incorrect (profile waits for config unnecessarily):**
+
+```typescript
+const [user, config] = await Promise.all([
+  fetchUser(),
+  fetchConfig()
+])
+const profile = await fetchProfile(user.id)
+```
+
+**Correct (config and profile run in parallel):**
+
+```typescript
+import { all } from 'better-all'
+
+const { user, config, profile } = await all({
+  async user() { return fetchUser() },
+  async config() { return fetchConfig() },
+  async profile() {
+    return fetchProfile((await this.$.user).id)
+  }
+})
+```
+
+**Alternative without extra dependencies:**
+
+We can also create all the promises first, and do `Promise.all()` at the end.
+
+```typescript
+const userPromise = fetchUser()
+const profilePromise = userPromise.then(user => fetchProfile(user.id))
+
+const [user, config, profile] = await Promise.all([
+  userPromise,
+  fetchConfig(),
+  profilePromise
+])
+```
+
+Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
diff --git a/skills/vercel-react-best-practices/rules/async-parallel.md b/skills/vercel-react-best-practices/rules/async-parallel.md
new file mode 100644
index 00000000..64133f6c
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-parallel.md
@@ -0,0 +1,28 @@
+---
+title: Promise.all() for Independent Operations
+impact: CRITICAL
+impactDescription: 2-10× improvement
+tags: async, parallelization, promises, waterfalls
+---
+
+## Promise.all() for Independent Operations
+
+When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
+
+**Incorrect (sequential execution, 3 round trips):**
+
+```typescript
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+```
+
+**Correct (parallel execution, 1 round trip):**
+
+```typescript
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
diff --git a/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md b/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
new file mode 100644
index 00000000..1fbc05b0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Strategic Suspense Boundaries
+impact: HIGH
+impactDescription: faster initial paint
+tags: async, suspense, streaming, layout-shift
+---
+
+## Strategic Suspense Boundaries
+
+Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
+
+**Incorrect (wrapper blocked by data fetching):**
+
+```tsx
+async function Page() {
+  const data = await fetchData() // Blocks entire page
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <DataDisplay data={data} />
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+```
+
+The entire layout waits for data even though only the middle section needs it.
+
+**Correct (wrapper shows immediately, data streams in):**
+
+```tsx
+function Page() {
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <div>
+        <Suspense fallback={<Skeleton />}>
+          <DataDisplay />
+        </Suspense>
+      </div>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+async function DataDisplay() {
+  const data = await fetchData() // Only blocks this component
+  return <div>{data.content}</div>
+}
+```
+
+Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
+
+**Alternative (share promise across components):**
+
+```tsx
+function Page() {
+  // Start fetch immediately, but don't await
+  const dataPromise = fetchData()
+  
+  return (
+    <div>
+      <div>Sidebar</div>
+      <div>Header</div>
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay dataPromise={dataPromise} />
+        <DataSummary dataPromise={dataPromise} />
+      </Suspense>
+      <div>Footer</div>
+    </div>
+  )
+}
+
+function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Unwraps the promise
+  return <div>{data.content}</div>
+}
+
+function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
+  const data = use(dataPromise) // Reuses the same promise
+  return <div>{data.summary}</div>
+}
+```
+
+Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
+
+**When NOT to use this pattern:**
+
+- Critical data needed for layout decisions (affects positioning)
+- SEO-critical content above the fold
+- Small, fast queries where suspense overhead isn't worth it
+- When you want to avoid layout shift (loading → content jump)
+
+**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
diff --git a/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md b/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
new file mode 100644
index 00000000..8276f156
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
@@ -0,0 +1,63 @@
+---
+title: Prefer Statically Analyzable Paths
+impact: HIGH
+impactDescription: avoids accidental broad bundles and file traces
+tags: bundle, nextjs, vite, webpack, rollup, esbuild, path
+---
+
+## Prefer Statically Analyzable Paths
+
+Build tools work best when import and file-system paths are obvious at build time. If you hide the real path inside a variable or compose it too dynamically, the tool either has to include a broad set of possible files, warn that it cannot analyze the import, or widen file tracing to stay safe.
+
+Prefer explicit maps or literal paths so the set of reachable files stays narrow and predictable. This is the same rule whether you are choosing modules with `import()` or reading files in server/build code.
+
+When analysis becomes too broad, the cost is real:
+- Larger server bundles
+- Slower builds
+- Worse cold starts
+- More memory use
+
+### Import Paths
+
+**Incorrect (the bundler cannot tell what may be imported):**
+
+```ts
+const PAGE_MODULES = {
+  home: './pages/home',
+  settings: './pages/settings',
+} as const
+
+const Page = await import(PAGE_MODULES[pageName])
+```
+
+**Correct (use an explicit map of allowed modules):**
+
+```ts
+const PAGE_MODULES = {
+  home: () => import('./pages/home'),
+  settings: () => import('./pages/settings'),
+} as const
+
+const Page = await PAGE_MODULES[pageName]()
+```
+
+### File-System Paths
+
+**Incorrect (a 2-value enum still hides the final path from static analysis):**
+
+```ts
+const baseDir = path.join(process.cwd(), 'content/' + contentKind)
+```
+
+**Correct (make each final path literal at the callsite):**
+
+```ts
+const baseDir =
+  kind === ContentKind.Blog
+    ? path.join(process.cwd(), 'content/blog')
+    : path.join(process.cwd(), 'content/docs')
+```
+
+In Next.js server code, this matters for output file tracing too. `path.join(process.cwd(), someVar)` can widen the traced file set because Next.js statically analyze `import`, `require`, and `fs` usage.
+
+Reference: [Next.js output](https://nextjs.org/docs/app/api-reference/config/next-config-js/output), [Next.js dynamic imports](https://nextjs.org/learn/seo/dynamic-imports), [Vite features](https://vite.dev/guide/features.html), [esbuild API](https://esbuild.github.io/api/), [Rollup dynamic import vars](https://www.npmjs.com/package/@rollup/plugin-dynamic-import-vars), [Webpack dependency management](https://webpack.js.org/guides/dependency-management/)
diff --git a/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md b/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
new file mode 100644
index 00000000..22d10501
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
@@ -0,0 +1,60 @@
+---
+title: Avoid Barrel File Imports
+impact: CRITICAL
+impactDescription: 200-800ms import cost, slow builds
+tags: bundle, imports, tree-shaking, barrel-files, performance
+---
+
+## Avoid Barrel File Imports
+
+Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
+
+Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
+
+**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
+
+**Incorrect (imports entire library):**
+
+```tsx
+import { Check, X, Menu } from 'lucide-react'
+// Loads 1,583 modules, takes ~2.8s extra in dev
+// Runtime cost: 200-800ms on every cold start
+
+import { Button, TextField } from '@mui/material'
+// Loads 2,225 modules, takes ~4.2s extra in dev
+```
+
+**Correct - Next.js 13.5+ (recommended):**
+
+```js
+// next.config.js - automatically optimizes barrel imports at build time
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+```tsx
+// Keep the standard imports - Next.js transforms them to direct imports
+import { Check, X, Menu } from 'lucide-react'
+// Full TypeScript support, no manual path wrangling
+```
+
+This is the recommended approach because it preserves TypeScript type safety and editor autocompletion while still eliminating the barrel import cost.
+
+**Correct - Direct imports (non-Next.js projects):**
+
+```tsx
+import Button from '@mui/material/Button'
+import TextField from '@mui/material/TextField'
+// Loads only what you use
+```
+
+> **TypeScript warning:** Some libraries (notably `lucide-react`) don't ship `.d.ts` files for their deep import paths. Importing from `lucide-react/dist/esm/icons/check` resolves to an implicit `any` type, causing errors under `strict` or `noImplicitAny`. Prefer `optimizePackageImports` when available, or verify the library exports types for its subpaths before using direct imports.
+
+These optimizations provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
+
+Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/skills/vercel-react-best-practices/rules/bundle-conditional.md b/skills/vercel-react-best-practices/rules/bundle-conditional.md
new file mode 100644
index 00000000..99d6fc90
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-conditional.md
@@ -0,0 +1,31 @@
+---
+title: Conditional Module Loading
+impact: HIGH
+impactDescription: loads large data only when needed
+tags: bundle, conditional-loading, lazy-loading
+---
+
+## Conditional Module Loading
+
+Load large data or modules only when a feature is activated.
+
+**Example (lazy-load animation frames):**
+
+```tsx
+function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
+  const [frames, setFrames] = useState<Frame[] | null>(null)
+
+  useEffect(() => {
+    if (enabled && !frames && typeof window !== 'undefined') {
+      import('./animation-frames.js')
+        .then(mod => setFrames(mod.frames))
+        .catch(() => setEnabled(false))
+    }
+  }, [enabled, frames, setEnabled])
+
+  if (!frames) return <Skeleton />
+  return <Canvas frames={frames} />
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
diff --git a/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md b/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
new file mode 100644
index 00000000..db041d15
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
@@ -0,0 +1,49 @@
+---
+title: Defer Non-Critical Third-Party Libraries
+impact: MEDIUM
+impactDescription: loads after hydration
+tags: bundle, third-party, analytics, defer
+---
+
+## Defer Non-Critical Third-Party Libraries
+
+Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
+
+**Incorrect (blocks initial bundle):**
+
+```tsx
+import { Analytics } from '@vercel/analytics/react'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
+
+**Correct (loads after hydration):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Analytics />
+      </body>
+    </html>
+  )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md b/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
new file mode 100644
index 00000000..60b62695
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
@@ -0,0 +1,35 @@
+---
+title: Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: directly affects TTI and LCP
+tags: bundle, dynamic-import, code-splitting, next-dynamic
+---
+
+## Dynamic Imports for Heavy Components
+
+Use `next/dynamic` to lazy-load large components not needed on initial render.
+
+**Incorrect (Monaco bundles with main chunk ~300KB):**
+
+```tsx
+import { MonacoEditor } from './monaco-editor'
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
+
+**Correct (Monaco loads on demand):**
+
+```tsx
+import dynamic from 'next/dynamic'
+
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+
+function CodePanel({ code }: { code: string }) {
+  return <MonacoEditor value={code} />
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/bundle-preload.md b/skills/vercel-react-best-practices/rules/bundle-preload.md
new file mode 100644
index 00000000..70005040
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/bundle-preload.md
@@ -0,0 +1,50 @@
+---
+title: Preload Based on User Intent
+impact: MEDIUM
+impactDescription: reduces perceived latency
+tags: bundle, preload, user-intent, hover
+---
+
+## Preload Based on User Intent
+
+Preload heavy bundles before they're needed to reduce perceived latency.
+
+**Example (preload on hover/focus):**
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+
+  return (
+    <button
+      onMouseEnter={preload}
+      onFocus={preload}
+      onClick={onClick}
+    >
+      Open Editor
+    </button>
+  )
+}
+```
+
+**Example (preload when feature flag is enabled):**
+
+```tsx
+function FlagsProvider({ children, flags }: Props) {
+  useEffect(() => {
+    if (flags.editorEnabled && typeof window !== 'undefined') {
+      void import('./monaco-editor').then(mod => mod.init())
+    }
+  }, [flags.editorEnabled])
+
+  return <FlagsContext.Provider value={flags}>
+    {children}
+  </FlagsContext.Provider>
+}
+```
+
+The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
diff --git a/skills/vercel-react-best-practices/rules/client-event-listeners.md b/skills/vercel-react-best-practices/rules/client-event-listeners.md
new file mode 100644
index 00000000..aad4ae91
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-event-listeners.md
@@ -0,0 +1,74 @@
+---
+title: Deduplicate Global Event Listeners
+impact: LOW
+impactDescription: single listener for N components
+tags: client, swr, event-listeners, subscription
+---
+
+## Deduplicate Global Event Listeners
+
+Use `useSWRSubscription()` to share global event listeners across component instances.
+
+**Incorrect (N instances = N listeners):**
+
+```tsx
+function useKeyboardShortcut(key: string, callback: () => void) {
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && e.key === key) {
+        callback()
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  }, [key, callback])
+}
+```
+
+When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
+
+**Correct (N instances = 1 listener):**
+
+```tsx
+import useSWRSubscription from 'swr/subscription'
+
+// Module-level Map to track callbacks per key
+const keyCallbacks = new Map<string, Set<() => void>>()
+
+function useKeyboardShortcut(key: string, callback: () => void) {
+  // Register this callback in the Map
+  useEffect(() => {
+    if (!keyCallbacks.has(key)) {
+      keyCallbacks.set(key, new Set())
+    }
+    keyCallbacks.get(key)!.add(callback)
+
+    return () => {
+      const set = keyCallbacks.get(key)
+      if (set) {
+        set.delete(callback)
+        if (set.size === 0) {
+          keyCallbacks.delete(key)
+        }
+      }
+    }
+  }, [key, callback])
+
+  useSWRSubscription('global-keydown', () => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey && keyCallbacks.has(e.key)) {
+        keyCallbacks.get(e.key)!.forEach(cb => cb())
+      }
+    }
+    window.addEventListener('keydown', handler)
+    return () => window.removeEventListener('keydown', handler)
+  })
+}
+
+function Profile() {
+  // Multiple shortcuts will share the same listener
+  useKeyboardShortcut('p', () => { /* ... */ }) 
+  useKeyboardShortcut('k', () => { /* ... */ })
+  // ...
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/client-localstorage-schema.md b/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
new file mode 100644
index 00000000..d30a1a7d
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
@@ -0,0 +1,71 @@
+---
+title: Version and Minimize localStorage Data
+impact: MEDIUM
+impactDescription: prevents schema conflicts, reduces storage size
+tags: client, localStorage, storage, versioning, data-minimization
+---
+
+## Version and Minimize localStorage Data
+
+Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
+
+**Incorrect:**
+
+```typescript
+// No version, stores everything, no error handling
+localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
+const data = localStorage.getItem('userConfig')
+```
+
+**Correct:**
+
+```typescript
+const VERSION = 'v2'
+
+function saveConfig(config: { theme: string; language: string }) {
+  try {
+    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
+  } catch {
+    // Throws in incognito/private browsing, quota exceeded, or disabled
+  }
+}
+
+function loadConfig() {
+  try {
+    const data = localStorage.getItem(`userConfig:${VERSION}`)
+    return data ? JSON.parse(data) : null
+  } catch {
+    return null
+  }
+}
+
+// Migration from v1 to v2
+function migrate() {
+  try {
+    const v1 = localStorage.getItem('userConfig:v1')
+    if (v1) {
+      const old = JSON.parse(v1)
+      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
+      localStorage.removeItem('userConfig:v1')
+    }
+  } catch {}
+}
+```
+
+**Store minimal fields from server responses:**
+
+```typescript
+// User object has 20+ fields, only store what UI needs
+function cachePrefs(user: FullUser) {
+  try {
+    localStorage.setItem('prefs:v1', JSON.stringify({
+      theme: user.preferences.theme,
+      notifications: user.preferences.notifications
+    }))
+  } catch {}
+}
+```
+
+**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
+
+**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
diff --git a/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md b/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
new file mode 100644
index 00000000..ce39a889
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
@@ -0,0 +1,48 @@
+---
+title: Use Passive Event Listeners for Scrolling Performance
+impact: MEDIUM
+impactDescription: eliminates scroll delay caused by event listeners
+tags: client, event-listeners, scrolling, performance, touch, wheel
+---
+
+## Use Passive Event Listeners for Scrolling Performance
+
+Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
+
+**Incorrect:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch)
+  document.addEventListener('wheel', handleWheel)
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Correct:**
+
+```typescript
+useEffect(() => {
+  const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
+  const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
+  
+  document.addEventListener('touchstart', handleTouch, { passive: true })
+  document.addEventListener('wheel', handleWheel, { passive: true })
+  
+  return () => {
+    document.removeEventListener('touchstart', handleTouch)
+    document.removeEventListener('wheel', handleWheel)
+  }
+}, [])
+```
+
+**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
+
+**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
diff --git a/skills/vercel-react-best-practices/rules/client-swr-dedup.md b/skills/vercel-react-best-practices/rules/client-swr-dedup.md
new file mode 100644
index 00000000..2a430f27
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/client-swr-dedup.md
@@ -0,0 +1,56 @@
+---
+title: Use SWR for Automatic Deduplication
+impact: MEDIUM-HIGH
+impactDescription: automatic deduplication
+tags: client, swr, deduplication, data-fetching
+---
+
+## Use SWR for Automatic Deduplication
+
+SWR enables request deduplication, caching, and revalidation across component instances.
+
+**Incorrect (no deduplication, each instance fetches):**
+
+```tsx
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users')
+      .then(r => r.json())
+      .then(setUsers)
+  }, [])
+}
+```
+
+**Correct (multiple instances share one request):**
+
+```tsx
+import useSWR from 'swr'
+
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+**For immutable data:**
+
+```tsx
+import { useImmutableSWR } from '@/lib/swr'
+
+function StaticContent() {
+  const { data } = useImmutableSWR('/api/config', fetcher)
+}
+```
+
+**For mutations:**
+
+```tsx
+import { useSWRMutation } from 'swr/mutation'
+
+function UpdateButton() {
+  const { trigger } = useSWRMutation('/api/user', updateUser)
+  return <button onClick={() => trigger()}>Update</button>
+}
+```
+
+Reference: [https://swr.vercel.app](https://swr.vercel.app)
diff --git a/skills/vercel-react-best-practices/rules/js-batch-dom-css.md b/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
new file mode 100644
index 00000000..a62d84ed
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
@@ -0,0 +1,107 @@
+---
+title: Avoid Layout Thrashing
+impact: MEDIUM
+impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
+tags: javascript, dom, css, performance, reflow, layout-thrashing
+---
+
+## Avoid Layout Thrashing
+
+Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
+
+**This is OK (browser batches style changes):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Each line invalidates style, but browser batches the recalculation
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+}
+```
+
+**Incorrect (interleaved reads and writes force reflows):**
+```typescript
+function layoutThrashing(element: HTMLElement) {
+  element.style.width = '100px'
+  const width = element.offsetWidth  // Forces reflow
+  element.style.height = '200px'
+  const height = element.offsetHeight  // Forces another reflow
+}
+```
+
+**Correct (batch writes, then read once):**
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  // Batch all writes together
+  element.style.width = '100px'
+  element.style.height = '200px'
+  element.style.backgroundColor = 'blue'
+  element.style.border = '1px solid black'
+  
+  // Read after all writes are done (single reflow)
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**Correct (batch reads, then writes):**
+```typescript
+function avoidThrashing(element: HTMLElement) {
+  // Read phase - all layout queries first
+  const rect1 = element.getBoundingClientRect()
+  const offsetWidth = element.offsetWidth
+  const offsetHeight = element.offsetHeight
+  
+  // Write phase - all style changes after
+  element.style.width = '100px'
+  element.style.height = '200px'
+}
+```
+
+**Better: use CSS classes**
+```css
+.highlighted-box {
+  width: 100px;
+  height: 200px;
+  background-color: blue;
+  border: 1px solid black;
+}
+```
+```typescript
+function updateElementStyles(element: HTMLElement) {
+  element.classList.add('highlighted-box')
+  
+  const { width, height } = element.getBoundingClientRect()
+}
+```
+
+**React example:**
+```tsx
+// Incorrect: interleaving style changes with layout queries
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  const ref = useRef<HTMLDivElement>(null)
+  
+  useEffect(() => {
+    if (ref.current && isHighlighted) {
+      ref.current.style.width = '100px'
+      const width = ref.current.offsetWidth // Forces layout
+      ref.current.style.height = '200px'
+    }
+  }, [isHighlighted])
+  
+  return <div ref={ref}>Content</div>
+}
+
+// Correct: toggle class
+function Box({ isHighlighted }: { isHighlighted: boolean }) {
+  return (
+    <div className={isHighlighted ? 'highlighted-box' : ''}>
+      Content
+    </div>
+  )
+}
+```
+
+Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
+
+See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
diff --git a/skills/vercel-react-best-practices/rules/js-cache-function-results.md b/skills/vercel-react-best-practices/rules/js-cache-function-results.md
new file mode 100644
index 00000000..180f8ac8
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-function-results.md
@@ -0,0 +1,80 @@
+---
+title: Cache Repeated Function Calls
+impact: MEDIUM
+impactDescription: avoid redundant computation
+tags: javascript, cache, memoization, performance
+---
+
+## Cache Repeated Function Calls
+
+Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
+
+**Incorrect (redundant computation):**
+
+```typescript
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // slugify() called 100+ times for same project names
+        const slug = slugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Correct (cached results):**
+
+```typescript
+// Module-level cache
+const slugifyCache = new Map<string, string>()
+
+function cachedSlugify(text: string): string {
+  if (slugifyCache.has(text)) {
+    return slugifyCache.get(text)!
+  }
+  const result = slugify(text)
+  slugifyCache.set(text, result)
+  return result
+}
+
+function ProjectList({ projects }: { projects: Project[] }) {
+  return (
+    <div>
+      {projects.map(project => {
+        // Computed only once per unique project name
+        const slug = cachedSlugify(project.name)
+        
+        return <ProjectCard key={project.id} slug={slug} />
+      })}
+    </div>
+  )
+}
+```
+
+**Simpler pattern for single-value functions:**
+
+```typescript
+let isLoggedInCache: boolean | null = null
+
+function isLoggedIn(): boolean {
+  if (isLoggedInCache !== null) {
+    return isLoggedInCache
+  }
+  
+  isLoggedInCache = document.cookie.includes('auth=')
+  return isLoggedInCache
+}
+
+// Clear cache when auth changes
+function onAuthChange() {
+  isLoggedInCache = null
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
diff --git a/skills/vercel-react-best-practices/rules/js-cache-property-access.md b/skills/vercel-react-best-practices/rules/js-cache-property-access.md
new file mode 100644
index 00000000..39eec906
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-property-access.md
@@ -0,0 +1,28 @@
+---
+title: Cache Property Access in Loops
+impact: LOW-MEDIUM
+impactDescription: reduces lookups
+tags: javascript, loops, optimization, caching
+---
+
+## Cache Property Access in Loops
+
+Cache object property lookups in hot paths.
+
+**Incorrect (3 lookups × N iterations):**
+
+```typescript
+for (let i = 0; i < arr.length; i++) {
+  process(obj.config.settings.value)
+}
+```
+
+**Correct (1 lookup total):**
+
+```typescript
+const value = obj.config.settings.value
+const len = arr.length
+for (let i = 0; i < len; i++) {
+  process(value)
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-cache-storage.md b/skills/vercel-react-best-practices/rules/js-cache-storage.md
new file mode 100644
index 00000000..aa4a30c0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-cache-storage.md
@@ -0,0 +1,70 @@
+---
+title: Cache Storage API Calls
+impact: LOW-MEDIUM
+impactDescription: reduces expensive I/O
+tags: javascript, localStorage, storage, caching, performance
+---
+
+## Cache Storage API Calls
+
+`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
+
+**Incorrect (reads storage on every call):**
+
+```typescript
+function getTheme() {
+  return localStorage.getItem('theme') ?? 'light'
+}
+// Called 10 times = 10 storage reads
+```
+
+**Correct (Map cache):**
+
+```typescript
+const storageCache = new Map<string, string | null>()
+
+function getLocalStorage(key: string) {
+  if (!storageCache.has(key)) {
+    storageCache.set(key, localStorage.getItem(key))
+  }
+  return storageCache.get(key)
+}
+
+function setLocalStorage(key: string, value: string) {
+  localStorage.setItem(key, value)
+  storageCache.set(key, value)  // keep cache in sync
+}
+```
+
+Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
+
+**Cookie caching:**
+
+```typescript
+let cookieCache: Record<string, string> | null = null
+
+function getCookie(name: string) {
+  if (!cookieCache) {
+    cookieCache = Object.fromEntries(
+      document.cookie.split('; ').map(c => c.split('='))
+    )
+  }
+  return cookieCache[name]
+}
+```
+
+**Important (invalidate on external changes):**
+
+If storage can change externally (another tab, server-set cookies), invalidate cache:
+
+```typescript
+window.addEventListener('storage', (e) => {
+  if (e.key) storageCache.delete(e.key)
+})
+
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') {
+    storageCache.clear()
+  }
+})
+```
diff --git a/skills/vercel-react-best-practices/rules/js-combine-iterations.md b/skills/vercel-react-best-practices/rules/js-combine-iterations.md
new file mode 100644
index 00000000..044d017e
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-combine-iterations.md
@@ -0,0 +1,32 @@
+---
+title: Combine Multiple Array Iterations
+impact: LOW-MEDIUM
+impactDescription: reduces iterations
+tags: javascript, arrays, loops, performance
+---
+
+## Combine Multiple Array Iterations
+
+Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
+
+**Incorrect (3 iterations):**
+
+```typescript
+const admins = users.filter(u => u.isAdmin)
+const testers = users.filter(u => u.isTester)
+const inactive = users.filter(u => !u.isActive)
+```
+
+**Correct (1 iteration):**
+
+```typescript
+const admins: User[] = []
+const testers: User[] = []
+const inactive: User[] = []
+
+for (const user of users) {
+  if (user.isAdmin) admins.push(user)
+  if (user.isTester) testers.push(user)
+  if (!user.isActive) inactive.push(user)
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-early-exit.md b/skills/vercel-react-best-practices/rules/js-early-exit.md
new file mode 100644
index 00000000..f46cb89c
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-early-exit.md
@@ -0,0 +1,50 @@
+---
+title: Early Return from Functions
+impact: LOW-MEDIUM
+impactDescription: avoids unnecessary computation
+tags: javascript, functions, optimization, early-return
+---
+
+## Early Return from Functions
+
+Return early when result is determined to skip unnecessary processing.
+
+**Incorrect (processes all items even after finding answer):**
+
+```typescript
+function validateUsers(users: User[]) {
+  let hasError = false
+  let errorMessage = ''
+  
+  for (const user of users) {
+    if (!user.email) {
+      hasError = true
+      errorMessage = 'Email required'
+    }
+    if (!user.name) {
+      hasError = true
+      errorMessage = 'Name required'
+    }
+    // Continues checking all users even after error found
+  }
+  
+  return hasError ? { valid: false, error: errorMessage } : { valid: true }
+}
+```
+
+**Correct (returns immediately on first error):**
+
+```typescript
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) {
+      return { valid: false, error: 'Email required' }
+    }
+    if (!user.name) {
+      return { valid: false, error: 'Name required' }
+    }
+  }
+
+  return { valid: true }
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/js-flatmap-filter.md b/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
new file mode 100644
index 00000000..ee0edf0d
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
@@ -0,0 +1,60 @@
+---
+title: Use flatMap to Map and Filter in One Pass
+impact: LOW-MEDIUM
+impactDescription: eliminates intermediate array
+tags: javascript, arrays, flatMap, filter, performance
+---
+
+## Use flatMap to Map and Filter in One Pass
+
+**Impact: LOW-MEDIUM (eliminates intermediate array)**
+
+Chaining `.map().filter(Boolean)` creates an intermediate array and iterates twice. Use `.flatMap()` to transform and filter in a single pass.
+
+**Incorrect (2 iterations, intermediate array):**
+
+```typescript
+const userNames = users
+  .map(user => user.isActive ? user.name : null)
+  .filter(Boolean)
+```
+
+**Correct (1 iteration, no intermediate array):**
+
+```typescript
+const userNames = users.flatMap(user =>
+  user.isActive ? [user.name] : []
+)
+```
+
+**More examples:**
+
+```typescript
+// Extract valid emails from responses
+// Before
+const emails = responses
+  .map(r => r.success ? r.data.email : null)
+  .filter(Boolean)
+
+// After
+const emails = responses.flatMap(r =>
+  r.success ? [r.data.email] : []
+)
+
+// Parse and filter valid numbers
+// Before
+const numbers = strings
+  .map(s => parseInt(s, 10))
+  .filter(n => !isNaN(n))
+
+// After
+const numbers = strings.flatMap(s => {
+  const n = parseInt(s, 10)
+  return isNaN(n) ? [] : [n]
+})
+```
+
+**When to use:**
+- Transforming items while filtering some out
+- Conditional mapping where some inputs produce no output
+- Parsing/validating where invalid inputs should be skipped
diff --git a/skills/vercel-react-best-practices/rules/js-hoist-regexp.md b/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
new file mode 100644
index 00000000..dae3fefd
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
@@ -0,0 +1,45 @@
+---
+title: Hoist RegExp Creation
+impact: LOW-MEDIUM
+impactDescription: avoids recreation
+tags: javascript, regexp, optimization, memoization
+---
+
+## Hoist RegExp Creation
+
+Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
+
+**Incorrect (new RegExp every render):**
+
+```tsx
+function Highlighter({ text, query }: Props) {
+  const regex = new RegExp(`(${query})`, 'gi')
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Correct (memoize or hoist):**
+
+```tsx
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+function Highlighter({ text, query }: Props) {
+  const regex = useMemo(
+    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
+    [query]
+  )
+  const parts = text.split(regex)
+  return <>{parts.map((part, i) => ...)}</>
+}
+```
+
+**Warning (global regex has mutable state):**
+
+Global regex (`/g`) has mutable `lastIndex` state:
+
+```typescript
+const regex = /foo/g
+regex.test('foo')  // true, lastIndex = 3
+regex.test('foo')  // false, lastIndex = 0
+```
diff --git a/skills/vercel-react-best-practices/rules/js-index-maps.md b/skills/vercel-react-best-practices/rules/js-index-maps.md
new file mode 100644
index 00000000..9d357a00
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-index-maps.md
@@ -0,0 +1,37 @@
+---
+title: Build Index Maps for Repeated Lookups
+impact: LOW-MEDIUM
+impactDescription: 1M ops to 2K ops
+tags: javascript, map, indexing, optimization, performance
+---
+
+## Build Index Maps for Repeated Lookups
+
+Multiple `.find()` calls by the same key should use a Map.
+
+**Incorrect (O(n) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  return orders.map(order => ({
+    ...order,
+    user: users.find(u => u.id === order.userId)
+  }))
+}
+```
+
+**Correct (O(1) per lookup):**
+
+```typescript
+function processOrders(orders: Order[], users: User[]) {
+  const userById = new Map(users.map(u => [u.id, u]))
+
+  return orders.map(order => ({
+    ...order,
+    user: userById.get(order.userId)
+  }))
+}
+```
+
+Build map once (O(n)), then all lookups are O(1).
+For 1000 orders × 1000 users: 1M ops → 2K ops.
diff --git a/skills/vercel-react-best-practices/rules/js-length-check-first.md b/skills/vercel-react-best-practices/rules/js-length-check-first.md
new file mode 100644
index 00000000..8b895736
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-length-check-first.md
@@ -0,0 +1,49 @@
+---
+title: Early Length Check for Array Comparisons
+impact: MEDIUM-HIGH
+impactDescription: avoids expensive operations when lengths differ
+tags: javascript, arrays, performance, optimization, comparison
+---
+
+## Early Length Check for Array Comparisons
+
+When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
+
+In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
+
+**Incorrect (always runs expensive comparison):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Always sorts and joins, even when lengths differ
+  return current.sort().join() !== original.sort().join()
+}
+```
+
+Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
+
+**Correct (O(1) length check first):**
+
+```typescript
+function hasChanges(current: string[], original: string[]) {
+  // Early return if lengths differ
+  if (current.length !== original.length) {
+    return true
+  }
+  // Only sort when lengths match
+  const currentSorted = current.toSorted()
+  const originalSorted = original.toSorted()
+  for (let i = 0; i < currentSorted.length; i++) {
+    if (currentSorted[i] !== originalSorted[i]) {
+      return true
+    }
+  }
+  return false
+}
+```
+
+This new approach is more efficient because:
+- It avoids the overhead of sorting and joining the arrays when lengths differ
+- It avoids consuming memory for the joined strings (especially important for large arrays)
+- It avoids mutating the original arrays
+- It returns early when a difference is found
diff --git a/skills/vercel-react-best-practices/rules/js-min-max-loop.md b/skills/vercel-react-best-practices/rules/js-min-max-loop.md
new file mode 100644
index 00000000..4b6656e9
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-min-max-loop.md
@@ -0,0 +1,82 @@
+---
+title: Use Loop for Min/Max Instead of Sort
+impact: LOW
+impactDescription: O(n) instead of O(n log n)
+tags: javascript, arrays, performance, sorting, algorithms
+---
+
+## Use Loop for Min/Max Instead of Sort
+
+Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
+
+**Incorrect (O(n log n) - sort to find latest):**
+
+```typescript
+interface Project {
+  id: string
+  name: string
+  updatedAt: number
+}
+
+function getLatestProject(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
+  return sorted[0]
+}
+```
+
+Sorts the entire array just to find the maximum value.
+
+**Incorrect (O(n log n) - sort for oldest and newest):**
+
+```typescript
+function getOldestAndNewest(projects: Project[]) {
+  const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
+  return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
+}
+```
+
+Still sorts unnecessarily when only min/max are needed.
+
+**Correct (O(n) - single loop):**
+
+```typescript
+function getLatestProject(projects: Project[]) {
+  if (projects.length === 0) return null
+  
+  let latest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt > latest.updatedAt) {
+      latest = projects[i]
+    }
+  }
+  
+  return latest
+}
+
+function getOldestAndNewest(projects: Project[]) {
+  if (projects.length === 0) return { oldest: null, newest: null }
+  
+  let oldest = projects[0]
+  let newest = projects[0]
+  
+  for (let i = 1; i < projects.length; i++) {
+    if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
+    if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
+  }
+  
+  return { oldest, newest }
+}
+```
+
+Single pass through the array, no copying, no sorting.
+
+**Alternative (Math.min/Math.max for small arrays):**
+
+```typescript
+const numbers = [5, 2, 8, 1, 9]
+const min = Math.min(...numbers)
+const max = Math.max(...numbers)
+```
+
+This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
diff --git a/skills/vercel-react-best-practices/rules/js-request-idle-callback.md b/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
new file mode 100644
index 00000000..d81927e5
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
@@ -0,0 +1,105 @@
+---
+title: Defer Non-Critical Work with requestIdleCallback
+impact: MEDIUM
+impactDescription: keeps UI responsive during background tasks
+tags: javascript, performance, idle, scheduling, analytics
+---
+
+## Defer Non-Critical Work with requestIdleCallback
+
+**Impact: MEDIUM (keeps UI responsive during background tasks)**
+
+Use `requestIdleCallback()` to schedule non-critical work during browser idle periods. This keeps the main thread free for user interactions and animations, reducing jank and improving perceived performance.
+
+**Incorrect (blocks main thread during user interaction):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // These block the main thread immediately
+  analytics.track('search', { query })
+  saveToRecentSearches(query)
+  prefetchTopResults(results.slice(0, 3))
+}
+```
+
+**Correct (defers non-critical work to idle time):**
+
+```typescript
+function handleSearch(query: string) {
+  const results = searchItems(query)
+  setResults(results)
+
+  // Defer non-critical work to idle periods
+  requestIdleCallback(() => {
+    analytics.track('search', { query })
+  })
+
+  requestIdleCallback(() => {
+    saveToRecentSearches(query)
+  })
+
+  requestIdleCallback(() => {
+    prefetchTopResults(results.slice(0, 3))
+  })
+}
+```
+
+**With timeout for required work:**
+
+```typescript
+// Ensure analytics fires within 2 seconds even if browser stays busy
+requestIdleCallback(
+  () => analytics.track('page_view', { path: location.pathname }),
+  { timeout: 2000 }
+)
+```
+
+**Chunking large tasks:**
+
+```typescript
+function processLargeDataset(items: Item[]) {
+  let index = 0
+
+  function processChunk(deadline: IdleDeadline) {
+    // Process items while we have idle time (aim for <50ms chunks)
+    while (index < items.length && deadline.timeRemaining() > 0) {
+      processItem(items[index])
+      index++
+    }
+
+    // Schedule next chunk if more items remain
+    if (index < items.length) {
+      requestIdleCallback(processChunk)
+    }
+  }
+
+  requestIdleCallback(processChunk)
+}
+```
+
+**With fallback for unsupported browsers:**
+
+```typescript
+const scheduleIdleWork = window.requestIdleCallback ?? ((cb: () => void) => setTimeout(cb, 1))
+
+scheduleIdleWork(() => {
+  // Non-critical work
+})
+```
+
+**When to use:**
+
+- Analytics and telemetry
+- Saving state to localStorage/IndexedDB
+- Prefetching resources for likely next actions
+- Processing non-urgent data transformations
+- Lazy initialization of non-critical features
+
+**When NOT to use:**
+
+- User-initiated actions that need immediate feedback
+- Rendering updates the user is waiting for
+- Time-sensitive operations
diff --git a/skills/vercel-react-best-practices/rules/js-set-map-lookups.md b/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
new file mode 100644
index 00000000..680a4892
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
@@ -0,0 +1,24 @@
+---
+title: Use Set/Map for O(1) Lookups
+impact: LOW-MEDIUM
+impactDescription: O(n) to O(1)
+tags: javascript, set, map, data-structures, performance
+---
+
+## Use Set/Map for O(1) Lookups
+
+Convert arrays to Set/Map for repeated membership checks.
+
+**Incorrect (O(n) per check):**
+
+```typescript
+const allowedIds = ['a', 'b', 'c', ...]
+items.filter(item => allowedIds.includes(item.id))
+```
+
+**Correct (O(1) per check):**
+
+```typescript
+const allowedIds = new Set(['a', 'b', 'c', ...])
+items.filter(item => allowedIds.has(item.id))
+```
diff --git a/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md b/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
new file mode 100644
index 00000000..eae8b3f8
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
@@ -0,0 +1,57 @@
+---
+title: Use toSorted() Instead of sort() for Immutability
+impact: MEDIUM-HIGH
+impactDescription: prevents mutation bugs in React state
+tags: javascript, arrays, immutability, react, state, mutation
+---
+
+## Use toSorted() Instead of sort() for Immutability
+
+`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
+
+**Incorrect (mutates original array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Mutates the users prop array!
+  const sorted = useMemo(
+    () => users.sort((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Correct (creates new array):**
+
+```typescript
+function UserList({ users }: { users: User[] }) {
+  // Creates new sorted array, original unchanged
+  const sorted = useMemo(
+    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
+    [users]
+  )
+  return <div>{sorted.map(renderUser)}</div>
+}
+```
+
+**Why this matters in React:**
+
+1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
+2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
+
+**Browser support (fallback for older browsers):**
+
+`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
+
+```typescript
+// Fallback for older browsers
+const sorted = [...items].sort((a, b) => a.value - b.value)
+```
+
+**Other immutable array methods:**
+
+- `.toSorted()` - immutable sort
+- `.toReversed()` - immutable reverse
+- `.toSpliced()` - immutable splice
+- `.with()` - immutable element replacement
diff --git a/skills/vercel-react-best-practices/rules/rendering-activity.md b/skills/vercel-react-best-practices/rules/rendering-activity.md
new file mode 100644
index 00000000..c957a490
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-activity.md
@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.
diff --git a/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md b/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
new file mode 100644
index 00000000..646744cb
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
@@ -0,0 +1,47 @@
+---
+title: Animate SVG Wrapper Instead of SVG Element
+impact: LOW
+impactDescription: enables hardware acceleration
+tags: rendering, svg, css, animation, performance
+---
+
+## Animate SVG Wrapper Instead of SVG Element
+
+Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
+
+**Incorrect (animating SVG directly - no hardware acceleration):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <svg 
+      className="animate-spin"
+      width="24" 
+      height="24" 
+      viewBox="0 0 24 24"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" />
+    </svg>
+  )
+}
+```
+
+**Correct (animating wrapper div - hardware accelerated):**
+
+```tsx
+function LoadingSpinner() {
+  return (
+    <div className="animate-spin">
+      <svg 
+        width="24" 
+        height="24" 
+        viewBox="0 0 24 24"
+      >
+        <circle cx="12" cy="12" r="10" stroke="currentColor" />
+      </svg>
+    </div>
+  )
+}
+```
+
+This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
diff --git a/skills/vercel-react-best-practices/rules/rendering-conditional-render.md b/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
new file mode 100644
index 00000000..7e866f58
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
@@ -0,0 +1,40 @@
+---
+title: Use Explicit Conditional Rendering
+impact: LOW
+impactDescription: prevents rendering 0 or NaN
+tags: rendering, conditional, jsx, falsy-values
+---
+
+## Use Explicit Conditional Rendering
+
+Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
+
+**Incorrect (renders "0" when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count && <span className="badge">{count}</span>}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div>0</div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
+
+**Correct (renders nothing when count is 0):**
+
+```tsx
+function Badge({ count }: { count: number }) {
+  return (
+    <div>
+      {count > 0 ? <span className="badge">{count}</span> : null}
+    </div>
+  )
+}
+
+// When count = 0, renders: <div></div>
+// When count = 5, renders: <div><span class="badge">5</span></div>
+```
diff --git a/skills/vercel-react-best-practices/rules/rendering-content-visibility.md b/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
new file mode 100644
index 00000000..aa665636
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
@@ -0,0 +1,38 @@
+---
+title: CSS content-visibility for Long Lists
+impact: HIGH
+impactDescription: faster initial render
+tags: rendering, css, content-visibility, long-lists
+---
+
+## CSS content-visibility for Long Lists
+
+Apply `content-visibility: auto` to defer off-screen rendering.
+
+**CSS:**
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+**Example:**
+
+```tsx
+function MessageList({ messages }: { messages: Message[] }) {
+  return (
+    <div className="overflow-y-auto h-screen">
+      {messages.map(msg => (
+        <div key={msg.id} className="message-item">
+          <Avatar user={msg.author} />
+          <div>{msg.content}</div>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
diff --git a/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md b/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
new file mode 100644
index 00000000..32d2f3fc
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
@@ -0,0 +1,46 @@
+---
+title: Hoist Static JSX Elements
+impact: LOW
+impactDescription: avoids re-creation
+tags: rendering, jsx, static, optimization
+---
+
+## Hoist Static JSX Elements
+
+Extract static JSX outside components to avoid re-creation.
+
+**Incorrect (recreates element every render):**
+
+```tsx
+function LoadingSkeleton() {
+  return <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+function Container() {
+  return (
+    <div>
+      {loading && <LoadingSkeleton />}
+    </div>
+  )
+}
+```
+
+**Correct (reuses same element):**
+
+```tsx
+const loadingSkeleton = (
+  <div className="animate-pulse h-20 bg-gray-200" />
+)
+
+function Container() {
+  return (
+    <div>
+      {loading && loadingSkeleton}
+    </div>
+  )
+}
+```
+
+This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
diff --git a/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md b/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
new file mode 100644
index 00000000..5cf0e79b
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
@@ -0,0 +1,82 @@
+---
+title: Prevent Hydration Mismatch Without Flickering
+impact: MEDIUM
+impactDescription: avoids visual flicker and hydration errors
+tags: rendering, ssr, hydration, localStorage, flicker
+---
+
+## Prevent Hydration Mismatch Without Flickering
+
+When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
+
+**Incorrect (breaks SSR):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  // localStorage is not available on server - throws error
+  const theme = localStorage.getItem('theme') || 'light'
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Server-side rendering will fail because `localStorage` is undefined.
+
+**Incorrect (visual flickering):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  const [theme, setTheme] = useState('light')
+  
+  useEffect(() => {
+    // Runs after hydration - causes visible flash
+    const stored = localStorage.getItem('theme')
+    if (stored) {
+      setTheme(stored)
+    }
+  }, [])
+  
+  return (
+    <div className={theme}>
+      {children}
+    </div>
+  )
+}
+```
+
+Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
+
+**Correct (no flicker, no hydration mismatch):**
+
+```tsx
+function ThemeWrapper({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <div id="theme-wrapper">
+        {children}
+      </div>
+      <script
+        dangerouslySetInnerHTML={{
+          __html: `
+            (function() {
+              try {
+                var theme = localStorage.getItem('theme') || 'light';
+                var el = document.getElementById('theme-wrapper');
+                if (el) el.className = theme;
+              } catch (e) {}
+            })();
+          `,
+        }}
+      />
+    </>
+  )
+}
+```
+
+The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
+
+This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
diff --git a/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md b/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
new file mode 100644
index 00000000..24ba2513
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
@@ -0,0 +1,30 @@
+---
+title: Suppress Expected Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: avoids noisy hydration warnings for known differences
+tags: rendering, hydration, ssr, nextjs
+---
+
+## Suppress Expected Hydration Mismatches
+
+In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
+
+**Incorrect (known mismatch warnings):**
+
+```tsx
+function Timestamp() {
+  return <span>{new Date().toLocaleString()}</span>
+}
+```
+
+**Correct (suppress expected mismatch only):**
+
+```tsx
+function Timestamp() {
+  return (
+    <span suppressHydrationWarning>
+      {new Date().toLocaleString()}
+    </span>
+  )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rendering-resource-hints.md b/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
new file mode 100644
index 00000000..1290bef0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
@@ -0,0 +1,85 @@
+---
+title: Use React DOM Resource Hints
+impact: HIGH
+impactDescription: reduces load time for critical resources
+tags: rendering, preload, preconnect, prefetch, resource-hints
+---
+
+## Use React DOM Resource Hints
+
+**Impact: HIGH (reduces load time for critical resources)**
+
+React DOM provides APIs to hint the browser about resources it will need. These are especially useful in server components to start loading resources before the client even receives the HTML.
+
+- **`prefetchDNS(href)`**: Resolve DNS for a domain you expect to connect to
+- **`preconnect(href)`**: Establish connection (DNS + TCP + TLS) to a server
+- **`preload(href, options)`**: Fetch a resource (stylesheet, font, script, image) you'll use soon
+- **`preloadModule(href)`**: Fetch an ES module you'll use soon
+- **`preinit(href, options)`**: Fetch and evaluate a stylesheet or script
+- **`preinitModule(href)`**: Fetch and evaluate an ES module
+
+**Example (preconnect to third-party APIs):**
+
+```tsx
+import { preconnect, prefetchDNS } from 'react-dom'
+
+export default function App() {
+  prefetchDNS('https://analytics.example.com')
+  preconnect('https://api.example.com')
+
+  return <main>{/* content */}</main>
+}
+```
+
+**Example (preload critical fonts and styles):**
+
+```tsx
+import { preload, preinit } from 'react-dom'
+
+export default function RootLayout({ children }) {
+  // Preload font file
+  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })
+
+  // Fetch and apply critical stylesheet immediately
+  preinit('/styles/critical.css', { as: 'style' })
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+
+**Example (preload modules for code-split routes):**
+
+```tsx
+import { preloadModule, preinitModule } from 'react-dom'
+
+function Navigation() {
+  const preloadDashboard = () => {
+    preloadModule('/dashboard.js', { as: 'script' })
+  }
+
+  return (
+    <nav>
+      <a href="/dashboard" onMouseEnter={preloadDashboard}>
+        Dashboard
+      </a>
+    </nav>
+  )
+}
+```
+
+**When to use each:**
+
+| API | Use case |
+|-----|----------|
+| `prefetchDNS` | Third-party domains you'll connect to later |
+| `preconnect` | APIs or CDNs you'll fetch from immediately |
+| `preload` | Critical resources needed for current page |
+| `preloadModule` | JS modules for likely next navigation |
+| `preinit` | Stylesheets/scripts that must execute early |
+| `preinitModule` | ES modules that must execute early |
+
+Reference: [React DOM Resource Preloading APIs](https://react.dev/reference/react-dom#resource-preloading-apis)
diff --git a/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md b/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
new file mode 100644
index 00000000..ee275ed1
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
@@ -0,0 +1,68 @@
+---
+title: Use defer or async on Script Tags
+impact: HIGH
+impactDescription: eliminates render-blocking
+tags: rendering, script, defer, async, performance
+---
+
+## Use defer or async on Script Tags
+
+**Impact: HIGH (eliminates render-blocking)**
+
+Script tags without `defer` or `async` block HTML parsing while the script downloads and executes. This delays First Contentful Paint and Time to Interactive.
+
+- **`defer`**: Downloads in parallel, executes after HTML parsing completes, maintains execution order
+- **`async`**: Downloads in parallel, executes immediately when ready, no guaranteed order
+
+Use `defer` for scripts that depend on DOM or other scripts. Use `async` for independent scripts like analytics.
+
+**Incorrect (blocks rendering):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        <script src="https://example.com/analytics.js" />
+        <script src="/scripts/utils.js" />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+export default function Document() {
+  return (
+    <html>
+      <head>
+        {/* Independent script - use async */}
+        <script src="https://example.com/analytics.js" async />
+        {/* DOM-dependent script - use defer */}
+        <script src="/scripts/utils.js" defer />
+      </head>
+      <body>{/* content */}</body>
+    </html>
+  )
+}
+```
+
+**Note:** In Next.js, prefer the `next/script` component with `strategy` prop instead of raw script tags:
+
+```tsx
+import Script from 'next/script'
+
+export default function Page() {
+  return (
+    <>
+      <Script src="https://example.com/analytics.js" strategy="afterInteractive" />
+      <Script src="/scripts/utils.js" strategy="beforeInteractive" />
+    </>
+  )
+}
+```
+
+Reference: [MDN - Script element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#defer)
diff --git a/skills/vercel-react-best-practices/rules/rendering-svg-precision.md b/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
new file mode 100644
index 00000000..6d771286
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
@@ -0,0 +1,28 @@
+---
+title: Optimize SVG Precision
+impact: LOW
+impactDescription: reduces file size
+tags: rendering, svg, optimization, svgo
+---
+
+## Optimize SVG Precision
+
+Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
+
+**Incorrect (excessive precision):**
+
+```svg
+<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
+```
+
+**Correct (1 decimal place):**
+
+```svg
+<path d="M 10.3 20.8 L 30.9 40.2" />
+```
+
+**Automate with SVGO:**
+
+```bash
+npx svgo --precision=1 --multipass icon.svg
+```
diff --git a/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md b/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
new file mode 100644
index 00000000..0c1b0b98
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
@@ -0,0 +1,75 @@
+---
+title: Use useTransition Over Manual Loading States
+impact: LOW
+impactDescription: reduces re-renders and improves code clarity
+tags: rendering, transitions, useTransition, loading, state
+---
+
+## Use useTransition Over Manual Loading States
+
+Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
+
+**Incorrect (manual loading state):**
+
+```tsx
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleSearch = async (value: string) => {
+    setIsLoading(true)
+    setQuery(value)
+    const data = await fetchResults(value)
+    setResults(data)
+    setIsLoading(false)
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Correct (useTransition with built-in pending state):**
+
+```tsx
+import { useTransition, useState } from 'react'
+
+function SearchResults() {
+  const [query, setQuery] = useState('')
+  const [results, setResults] = useState([])
+  const [isPending, startTransition] = useTransition()
+
+  const handleSearch = (value: string) => {
+    setQuery(value) // Update input immediately
+    
+    startTransition(async () => {
+      // Fetch and update results
+      const data = await fetchResults(value)
+      setResults(data)
+    })
+  }
+
+  return (
+    <>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isPending && <Spinner />}
+      <ResultsList results={results} />
+    </>
+  )
+}
+```
+
+**Benefits:**
+
+- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
+- **Error resilience**: Pending state correctly resets even if the transition throws
+- **Better responsiveness**: Keeps the UI responsive during updates
+- **Interrupt handling**: New transitions automatically cancel pending ones
+
+Reference: [useTransition](https://react.dev/reference/react/useTransition)
diff --git a/skills/vercel-react-best-practices/rules/rerender-defer-reads.md b/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
new file mode 100644
index 00000000..e867c95f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
@@ -0,0 +1,39 @@
+---
+title: Defer State Reads to Usage Point
+impact: MEDIUM
+impactDescription: avoids unnecessary subscriptions
+tags: rerender, searchParams, localStorage, optimization
+---
+
+## Defer State Reads to Usage Point
+
+Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
+
+**Incorrect (subscribes to all searchParams changes):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const searchParams = useSearchParams()
+
+  const handleShare = () => {
+    const ref = searchParams.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
+
+**Correct (reads on demand, no subscription):**
+
+```tsx
+function ShareButton({ chatId }: { chatId: string }) {
+  const handleShare = () => {
+    const params = new URLSearchParams(window.location.search)
+    const ref = params.get('ref')
+    shareChat(chatId, { ref })
+  }
+
+  return <button onClick={handleShare}>Share</button>
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-dependencies.md b/skills/vercel-react-best-practices/rules/rerender-dependencies.md
new file mode 100644
index 00000000..47a4d926
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-dependencies.md
@@ -0,0 +1,45 @@
+---
+title: Narrow Effect Dependencies
+impact: LOW
+impactDescription: minimizes effect re-runs
+tags: rerender, useEffect, dependencies, optimization
+---
+
+## Narrow Effect Dependencies
+
+Specify primitive dependencies instead of objects to minimize effect re-runs.
+
+**Incorrect (re-runs on any user field change):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+```
+
+**Correct (re-runs only when id changes):**
+
+```tsx
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+**For derived state, compute outside effect:**
+
+```tsx
+// Incorrect: runs on width=767, 766, 765...
+useEffect(() => {
+  if (width < 768) {
+    enableMobileMode()
+  }
+}, [width])
+
+// Correct: runs only on boolean transition
+const isMobile = width < 768
+useEffect(() => {
+  if (isMobile) {
+    enableMobileMode()
+  }
+}, [isMobile])
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md b/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
new file mode 100644
index 00000000..3d9fe405
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
@@ -0,0 +1,40 @@
+---
+title: Calculate Derived State During Rendering
+impact: MEDIUM
+impactDescription: avoids redundant renders and state drift
+tags: rerender, derived-state, useEffect, state
+---
+
+## Calculate Derived State During Rendering
+
+If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
+
+**Incorrect (redundant state and effect):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const [fullName, setFullName] = useState('')
+
+  useEffect(() => {
+    setFullName(firstName + ' ' + lastName)
+  }, [firstName, lastName])
+
+  return <p>{fullName}</p>
+}
+```
+
+**Correct (derive during render):**
+
+```tsx
+function Form() {
+  const [firstName, setFirstName] = useState('First')
+  const [lastName, setLastName] = useState('Last')
+  const fullName = firstName + ' ' + lastName
+
+  return <p>{fullName}</p>
+}
+```
+
+References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
diff --git a/skills/vercel-react-best-practices/rules/rerender-derived-state.md b/skills/vercel-react-best-practices/rules/rerender-derived-state.md
new file mode 100644
index 00000000..e5c899f6
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-derived-state.md
@@ -0,0 +1,29 @@
+---
+title: Subscribe to Derived State
+impact: MEDIUM
+impactDescription: reduces re-render frequency
+tags: rerender, derived-state, media-query, optimization
+---
+
+## Subscribe to Derived State
+
+Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
+
+**Incorrect (re-renders on every pixel change):**
+
+```tsx
+function Sidebar() {
+  const width = useWindowWidth()  // updates continuously
+  const isMobile = width < 768
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
+
+**Correct (re-renders only when boolean changes):**
+
+```tsx
+function Sidebar() {
+  const isMobile = useMediaQuery('(max-width: 767px)')
+  return <nav className={isMobile ? 'mobile' : 'desktop'} />
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md b/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
new file mode 100644
index 00000000..b004ef45
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
@@ -0,0 +1,74 @@
+---
+title: Use Functional setState Updates
+impact: MEDIUM
+impactDescription: prevents stale closures and unnecessary callback recreations
+tags: react, hooks, useState, useCallback, callbacks, closures
+---
+
+## Use Functional setState Updates
+
+When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
+
+**Incorrect (requires state as dependency):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Callback must depend on items, recreated on every items change
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems([...items, ...newItems])
+  }, [items])  // ❌ items dependency causes recreations
+  
+  // Risk of stale closure if dependency is forgotten
+  const removeItem = useCallback((id: string) => {
+    setItems(items.filter(item => item.id !== id))
+  }, [])  // ❌ Missing items dependency - will use stale items!
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
+
+**Correct (stable callbacks, no stale closures):**
+
+```tsx
+function TodoList() {
+  const [items, setItems] = useState(initialItems)
+  
+  // Stable callback, never recreated
+  const addItems = useCallback((newItems: Item[]) => {
+    setItems(curr => [...curr, ...newItems])
+  }, [])  // ✅ No dependencies needed
+  
+  // Always uses latest state, no stale closure risk
+  const removeItem = useCallback((id: string) => {
+    setItems(curr => curr.filter(item => item.id !== id))
+  }, [])  // ✅ Safe and stable
+  
+  return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
+}
+```
+
+**Benefits:**
+
+1. **Stable callback references** - Callbacks don't need to be recreated when state changes
+2. **No stale closures** - Always operates on the latest state value
+3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
+4. **Prevents bugs** - Eliminates the most common source of React closure bugs
+
+**When to use functional updates:**
+
+- Any setState that depends on the current state value
+- Inside useCallback/useMemo when state is needed
+- Event handlers that reference state
+- Async operations that update state
+
+**When direct updates are fine:**
+
+- Setting state to a static value: `setCount(0)`
+- Setting state from props/arguments only: `setName(newName)`
+- State doesn't depend on previous value
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
diff --git a/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md b/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
new file mode 100644
index 00000000..4ecb350f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
@@ -0,0 +1,58 @@
+---
+title: Use Lazy State Initialization
+impact: MEDIUM
+impactDescription: wasted computation on every render
+tags: react, hooks, useState, performance, initialization
+---
+
+## Use Lazy State Initialization
+
+Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
+
+**Incorrect (runs on every render):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs on EVERY render, even after initialization
+  const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  // When query changes, buildSearchIndex runs again unnecessarily
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs on every render
+  const [settings, setSettings] = useState(
+    JSON.parse(localStorage.getItem('settings') || '{}')
+  )
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+**Correct (runs only once):**
+
+```tsx
+function FilteredList({ items }: { items: Item[] }) {
+  // buildSearchIndex() runs ONLY on initial render
+  const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
+  const [query, setQuery] = useState('')
+  
+  return <SearchResults index={searchIndex} query={query} />
+}
+
+function UserProfile() {
+  // JSON.parse runs only on initial render
+  const [settings, setSettings] = useState(() => {
+    const stored = localStorage.getItem('settings')
+    return stored ? JSON.parse(stored) : {}
+  })
+  
+  return <SettingsForm settings={settings} onChange={setSettings} />
+}
+```
+
+Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
+
+For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
diff --git a/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md b/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
new file mode 100644
index 00000000..63570491
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
@@ -0,0 +1,38 @@
+---
+
+title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+impact: MEDIUM
+impactDescription: restores memoization by using a constant for default value
+tags: rerender, memo, optimization
+
+---
+
+## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
+
+When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
+
+To address this issue, extract the default value into a constant.
+
+**Incorrect (`onClick` has different values on every rerender):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
+
+**Correct (stable default value):**
+
+```tsx
+const NOOP = () => {};
+
+const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
+  // ...
+})
+
+// Used without optional onClick
+<UserAvatar />
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-memo.md b/skills/vercel-react-best-practices/rules/rerender-memo.md
new file mode 100644
index 00000000..f8982ab6
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-memo.md
@@ -0,0 +1,44 @@
+---
+title: Extract to Memoized Components
+impact: MEDIUM
+impactDescription: enables early returns
+tags: rerender, memo, useMemo, optimization
+---
+
+## Extract to Memoized Components
+
+Extract expensive work into memoized components to enable early returns before computation.
+
+**Incorrect (computes avatar even when loading):**
+
+```tsx
+function Profile({ user, loading }: Props) {
+  const avatar = useMemo(() => {
+    const id = computeAvatarId(user)
+    return <Avatar id={id} />
+  }, [user])
+
+  if (loading) return <Skeleton />
+  return <div>{avatar}</div>
+}
+```
+
+**Correct (skips computation when loading):**
+
+```tsx
+const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
+  const id = useMemo(() => computeAvatarId(user), [user])
+  return <Avatar id={id} />
+})
+
+function Profile({ user, loading }: Props) {
+  if (loading) return <Skeleton />
+  return (
+    <div>
+      <UserAvatar user={user} />
+    </div>
+  )
+}
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
diff --git a/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md b/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
new file mode 100644
index 00000000..dd58a1af
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
@@ -0,0 +1,45 @@
+---
+title: Put Interaction Logic in Event Handlers
+impact: MEDIUM
+impactDescription: avoids effect re-runs and duplicate side effects
+tags: rerender, useEffect, events, side-effects, dependencies
+---
+
+## Put Interaction Logic in Event Handlers
+
+If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
+
+**Incorrect (event modeled as state + effect):**
+
+```tsx
+function Form() {
+  const [submitted, setSubmitted] = useState(false)
+  const theme = useContext(ThemeContext)
+
+  useEffect(() => {
+    if (submitted) {
+      post('/api/register')
+      showToast('Registered', theme)
+    }
+  }, [submitted, theme])
+
+  return <button onClick={() => setSubmitted(true)}>Submit</button>
+}
+```
+
+**Correct (do it in the handler):**
+
+```tsx
+function Form() {
+  const theme = useContext(ThemeContext)
+
+  function handleSubmit() {
+    post('/api/register')
+    showToast('Registered', theme)
+  }
+
+  return <button onClick={handleSubmit}>Submit</button>
+}
+```
+
+Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
diff --git a/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md b/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
new file mode 100644
index 00000000..d97592ac
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
@@ -0,0 +1,82 @@
+---
+title: Don't Define Components Inside Components
+impact: HIGH
+impactDescription: prevents remount on every render
+tags: rerender, components, remount, performance
+---
+
+## Don't Define Components Inside Components
+
+**Impact: HIGH (prevents remount on every render)**
+
+Defining a component inside another component creates a new component type on every render. React sees a different component each time and fully remounts it, destroying all state and DOM.
+
+A common reason developers do this is to access parent variables without passing props. Always pass props instead.
+
+**Incorrect (remounts on every render):**
+
+```tsx
+function UserProfile({ user, theme }) {
+  // Defined inside to access `theme` - BAD
+  const Avatar = () => (
+    <img
+      src={user.avatarUrl}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+
+  // Defined inside to access `user` - BAD
+  const Stats = () => (
+    <div>
+      <span>{user.followers} followers</span>
+      <span>{user.posts} posts</span>
+    </div>
+  )
+
+  return (
+    <div>
+      <Avatar />
+      <Stats />
+    </div>
+  )
+}
+```
+
+Every time `UserProfile` renders, `Avatar` and `Stats` are new component types. React unmounts the old instances and mounts new ones, losing any internal state, running effects again, and recreating DOM nodes.
+
+**Correct (pass props instead):**
+
+```tsx
+function Avatar({ src, theme }: { src: string; theme: string }) {
+  return (
+    <img
+      src={src}
+      className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'}
+    />
+  )
+}
+
+function Stats({ followers, posts }: { followers: number; posts: number }) {
+  return (
+    <div>
+      <span>{followers} followers</span>
+      <span>{posts} posts</span>
+    </div>
+  )
+}
+
+function UserProfile({ user, theme }) {
+  return (
+    <div>
+      <Avatar src={user.avatarUrl} theme={theme} />
+      <Stats followers={user.followers} posts={user.posts} />
+    </div>
+  )
+}
+```
+
+**Symptoms of this bug:**
+- Input fields lose focus on every keystroke
+- Animations restart unexpectedly
+- `useEffect` cleanup/setup runs on every parent render
+- Scroll position resets inside the component
diff --git a/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md b/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
new file mode 100644
index 00000000..59dfab0f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
@@ -0,0 +1,35 @@
+---
+title: Do not wrap a simple expression with a primitive result type in useMemo
+impact: LOW-MEDIUM
+impactDescription: wasted computation on every render
+tags: rerender, useMemo, optimization
+---
+
+## Do not wrap a simple expression with a primitive result type in useMemo
+
+When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
+Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
+
+**Incorrect:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = useMemo(() => {
+    return user.isLoading || notifications.isLoading
+  }, [user.isLoading, notifications.isLoading])
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
+
+**Correct:**
+
+```tsx
+function Header({ user, notifications }: Props) {
+  const isLoading = user.isLoading || notifications.isLoading
+
+  if (isLoading) return <Skeleton />
+  // return some markup
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md b/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
new file mode 100644
index 00000000..89d80564
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
@@ -0,0 +1,64 @@
+---
+title: Split Combined Hook Computations
+impact: MEDIUM
+impactDescription: avoids recomputing independent steps
+tags: rerender, useMemo, useEffect, dependencies, optimization
+---
+
+## Split Combined Hook Computations
+
+When a hook contains multiple independent tasks with different dependencies, split them into separate hooks. A combined hook reruns all tasks when any dependency changes, even if some tasks don't use the changed value.
+
+**Incorrect (changing `sortOrder` recomputes filtering):**
+
+```tsx
+const sortedProducts = useMemo(() => {
+  const filtered = products.filter((p) => p.category === category)
+  const sorted = filtered.toSorted((a, b) =>
+    sortOrder === "asc" ? a.price - b.price : b.price - a.price
+  )
+  return sorted
+}, [products, category, sortOrder])
+```
+
+**Correct (filtering only recomputes when products or category change):**
+
+```tsx
+const filteredProducts = useMemo(
+  () => products.filter((p) => p.category === category),
+  [products, category]
+)
+
+const sortedProducts = useMemo(
+  () =>
+    filteredProducts.toSorted((a, b) =>
+      sortOrder === "asc" ? a.price - b.price : b.price - a.price
+    ),
+  [filteredProducts, sortOrder]
+)
+```
+
+This pattern also applies to `useEffect` when combining unrelated side effects:
+
+**Incorrect (both effects run when either dependency changes):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+  document.title = `${pageTitle} | My App`
+}, [pathname, pageTitle])
+```
+
+**Correct (effects run independently):**
+
+```tsx
+useEffect(() => {
+  analytics.trackPageView(pathname)
+}, [pathname])
+
+useEffect(() => {
+  document.title = `${pageTitle} | My App`
+}, [pageTitle])
+```
+
+**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, it automatically optimizes dependency tracking and may handle some of these cases for you.
diff --git a/skills/vercel-react-best-practices/rules/rerender-transitions.md b/skills/vercel-react-best-practices/rules/rerender-transitions.md
new file mode 100644
index 00000000..d99f43f7
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-transitions.md
@@ -0,0 +1,40 @@
+---
+title: Use Transitions for Non-Urgent Updates
+impact: MEDIUM
+impactDescription: maintains UI responsiveness
+tags: rerender, transitions, startTransition, performance
+---
+
+## Use Transitions for Non-Urgent Updates
+
+Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
+
+**Incorrect (blocks UI on every scroll):**
+
+```tsx
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => setScrollY(window.scrollY)
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+**Correct (non-blocking updates):**
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md b/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
new file mode 100644
index 00000000..619c04b0
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
@@ -0,0 +1,59 @@
+---
+title: Use useDeferredValue for Expensive Derived Renders
+impact: MEDIUM
+impactDescription: keeps input responsive during heavy computation
+tags: rerender, useDeferredValue, optimization, concurrent
+---
+
+## Use useDeferredValue for Expensive Derived Renders
+
+When user input triggers expensive computations or renders, use `useDeferredValue` to keep the input responsive. The deferred value lags behind, allowing React to prioritize the input update and render the expensive result when idle.
+
+**Incorrect (input feels laggy while filtering):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const filtered = items.filter(item => fuzzyMatch(item, query))
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <ResultsList results={filtered} />
+    </>
+  )
+}
+```
+
+**Correct (input stays snappy, results render when ready):**
+
+```tsx
+function Search({ items }: { items: Item[] }) {
+  const [query, setQuery] = useState('')
+  const deferredQuery = useDeferredValue(query)
+  const filtered = useMemo(
+    () => items.filter(item => fuzzyMatch(item, deferredQuery)),
+    [items, deferredQuery]
+  )
+  const isStale = query !== deferredQuery
+
+  return (
+    <>
+      <input value={query} onChange={e => setQuery(e.target.value)} />
+      <div style={{ opacity: isStale ? 0.7 : 1 }}>
+        <ResultsList results={filtered} />
+      </div>
+    </>
+  )
+}
+```
+
+**When to use:**
+
+- Filtering/searching large lists
+- Expensive visualizations (charts, graphs) reacting to input
+- Any derived state that causes noticeable render delays
+
+**Note:** Wrap the expensive computation in `useMemo` with the deferred value as a dependency, otherwise it still runs on every render.
+
+Reference: [React useDeferredValue](https://react.dev/reference/react/useDeferredValue)
diff --git a/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md b/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
new file mode 100644
index 00000000..cf04b81f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
@@ -0,0 +1,73 @@
+---
+title: Use useRef for Transient Values
+impact: MEDIUM
+impactDescription: avoids unnecessary re-renders on frequent updates
+tags: rerender, useref, state, performance
+---
+
+## Use useRef for Transient Values
+
+When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
+
+**Incorrect (renders every update):**
+
+```tsx
+function Tracker() {
+  const [lastX, setLastX] = useState(0)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => setLastX(e.clientX)
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: lastX,
+        width: 8,
+        height: 8,
+        background: 'black',
+      }}
+    />
+  )
+}
+```
+
+**Correct (no re-render for tracking):**
+
+```tsx
+function Tracker() {
+  const lastXRef = useRef(0)
+  const dotRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    const onMove = (e: MouseEvent) => {
+      lastXRef.current = e.clientX
+      const node = dotRef.current
+      if (node) {
+        node.style.transform = `translateX(${e.clientX}px)`
+      }
+    }
+    window.addEventListener('mousemove', onMove)
+    return () => window.removeEventListener('mousemove', onMove)
+  }, [])
+
+  return (
+    <div
+      ref={dotRef}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        width: 8,
+        height: 8,
+        background: 'black',
+        transform: 'translateX(0px)',
+      }}
+    />
+  )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/server-after-nonblocking.md b/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
new file mode 100644
index 00000000..e8f5b260
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
diff --git a/skills/vercel-react-best-practices/rules/server-auth-actions.md b/skills/vercel-react-best-practices/rules/server-auth-actions.md
new file mode 100644
index 00000000..ee82c044
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-auth-actions.md
@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
diff --git a/skills/vercel-react-best-practices/rules/server-cache-lru.md b/skills/vercel-react-best-practices/rules/server-cache-lru.md
new file mode 100644
index 00000000..ef6938aa
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-cache-lru.md
@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
diff --git a/skills/vercel-react-best-practices/rules/server-cache-react.md b/skills/vercel-react-best-practices/rules/server-cache-react.md
new file mode 100644
index 00000000..87c9ca33
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-cache-react.md
@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)
diff --git a/skills/vercel-react-best-practices/rules/server-dedup-props.md b/skills/vercel-react-best-practices/rules/server-dedup-props.md
new file mode 100644
index 00000000..fb24a256
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-dedup-props.md
@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
diff --git a/skills/vercel-react-best-practices/rules/server-hoist-static-io.md b/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
new file mode 100644
index 00000000..25205c2f
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
@@ -0,0 +1,149 @@
+---
+title: Hoist Static I/O to Module Level
+impact: HIGH
+impactDescription: avoids repeated file/network I/O per request
+tags: server, io, performance, next.js, route-handlers, og-image
+---
+
+## Hoist Static I/O to Module Level
+
+**Impact: HIGH (avoids repeated file/network I/O per request)**
+
+When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
+
+**Incorrect (reads font file on every request):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+export async function GET(request: Request) {
+  // Runs on EVERY request - expensive!
+  const fontData = await fetch(
+    new URL('./fonts/Inter.ttf', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  const logoData = await fetch(
+    new URL('./images/logo.png', import.meta.url)
+  ).then(res => res.arrayBuffer())
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Correct (loads once at module initialization):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+
+// Module-level: runs ONCE when module is first imported
+const fontData = fetch(
+  new URL('./fonts/Inter.ttf', import.meta.url)
+).then(res => res.arrayBuffer())
+
+const logoData = fetch(
+  new URL('./images/logo.png', import.meta.url)
+).then(res => res.arrayBuffer())
+
+export async function GET(request: Request) {
+  // Await the already-started promises
+  const [font, logo] = await Promise.all([fontData, logoData])
+
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logo} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: font }] }
+  )
+}
+```
+
+**Correct (synchronous fs at module level):**
+
+```typescript
+// app/api/og/route.tsx
+import { ImageResponse } from 'next/og'
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+// Synchronous read at module level - blocks only during module init
+const fontData = readFileSync(
+  join(process.cwd(), 'public/fonts/Inter.ttf')
+)
+
+const logoData = readFileSync(
+  join(process.cwd(), 'public/images/logo.png')
+)
+
+export async function GET(request: Request) {
+  return new ImageResponse(
+    <div style={{ fontFamily: 'Inter' }}>
+      <img src={logoData} />
+      Hello World
+    </div>,
+    { fonts: [{ name: 'Inter', data: fontData }] }
+  )
+}
+```
+
+**Incorrect (reads config on every call):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+export async function processRequest(data: Data) {
+  const config = JSON.parse(
+    await fs.readFile('./config.json', 'utf-8')
+  )
+  const template = await fs.readFile('./template.html', 'utf-8')
+
+  return render(template, data, config)
+}
+```
+
+**Correct (hoists config and template to module level):**
+
+```typescript
+import fs from 'node:fs/promises'
+
+const configPromise = fs
+  .readFile('./config.json', 'utf-8')
+  .then(JSON.parse)
+const templatePromise = fs.readFile('./template.html', 'utf-8')
+
+export async function processRequest(data: Data) {
+  const [config, template] = await Promise.all([
+    configPromise,
+    templatePromise,
+  ])
+
+  return render(template, data, config)
+}
+```
+
+When to use this pattern:
+
+- Loading fonts for OG image generation
+- Loading static logos, icons, or watermarks
+- Reading configuration files that don't change at runtime
+- Loading email templates or other static templates
+- Any static asset that's the same across all requests
+
+When not to use this pattern:
+
+- Assets that vary per request or user
+- Files that may change during runtime (use caching with TTL instead)
+- Large files that would consume too much memory if kept loaded
+- Sensitive data that shouldn't persist in memory
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
+
+In traditional serverless, each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.
diff --git a/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md b/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
new file mode 100644
index 00000000..ff7d9f29
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
@@ -0,0 +1,50 @@
+---
+title: Avoid Shared Module State for Request Data
+impact: HIGH
+impactDescription: prevents concurrency bugs and request data leaks
+tags: server, rsc, ssr, concurrency, security, state
+---
+
+## Avoid Shared Module State for Request Data
+
+For React Server Components and client components rendered during SSR, avoid using mutable module-level variables to share request-scoped data. Server renders can run concurrently in the same process. If one render writes to shared module state and another render reads it, you can get race conditions, cross-request contamination, and security bugs where one user's data appears in another user's response.
+
+Treat module scope on the server as process-wide shared memory, not request-local state.
+
+**Incorrect (request data leaks across concurrent renders):**
+
+```tsx
+let currentUser: User | null = null
+
+export default async function Page() {
+  currentUser = await auth()
+  return <Dashboard />
+}
+
+async function Dashboard() {
+  return <div>{currentUser?.name}</div>
+}
+```
+
+If two requests overlap, request A can set `currentUser`, then request B overwrites it before request A finishes rendering `Dashboard`.
+
+**Correct (keep request data local to the render tree):**
+
+```tsx
+export default async function Page() {
+  const user = await auth()
+  return <Dashboard user={user} />
+}
+
+function Dashboard({ user }: { user: User | null }) {
+  return <div>{user?.name}</div>
+}
+```
+
+Safe exceptions:
+
+- Immutable static assets or config loaded once at module scope
+- Shared caches intentionally designed for cross-request reuse and keyed correctly
+- Process-wide singletons that do not store request- or user-specific mutable data
+
+For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
diff --git a/skills/vercel-react-best-practices/rules/server-parallel-fetching.md b/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
new file mode 100644
index 00000000..1affc835
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```
diff --git a/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md b/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
new file mode 100644
index 00000000..be1dc250
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
@@ -0,0 +1,34 @@
+---
+title: Parallel Nested Data Fetching
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, promise-chaining
+---
+
+## Parallel Nested Data Fetching
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect (a single slow item blocks all nested fetches):**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct (each item chains its own nested fetch):**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.
diff --git a/skills/vercel-react-best-practices/rules/server-serialization.md b/skills/vercel-react-best-practices/rules/server-serialization.md
new file mode 100644
index 00000000..39c5c416
--- /dev/null
+++ b/skills/vercel-react-best-practices/rules/server-serialization.md
@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```
diff --git a/skills/vercel-react-native-skills/AGENTS.md b/skills/vercel-react-native-skills/AGENTS.md
new file mode 100644
index 00000000..d263eb9c
--- /dev/null
+++ b/skills/vercel-react-native-skills/AGENTS.md
@@ -0,0 +1,2897 @@
+# React Native Skills
+
+**Version 1.0.0**  
+Engineering  
+January 2026
+
+> **Note:**  
+> This document is mainly for agents and LLMs to follow when maintaining,  
+> generating, or refactoring React Native codebases. Humans  
+> may also find it useful, but guidance here is optimized for automation  
+> and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.
+
+---
+
+## Table of Contents
+
+1. [Core Rendering](#1-core-rendering) — **CRITICAL**
+   - 1.1 [Never Use && with Potentially Falsy Values](#11-never-use--with-potentially-falsy-values)
+   - 1.2 [Wrap Strings in Text Components](#12-wrap-strings-in-text-components)
+2. [List Performance](#2-list-performance) — **HIGH**
+   - 2.1 [Avoid Inline Objects in renderItem](#21-avoid-inline-objects-in-renderitem)
+   - 2.2 [Hoist callbacks to the root of lists](#22-hoist-callbacks-to-the-root-of-lists)
+   - 2.3 [Keep List Items Lightweight](#23-keep-list-items-lightweight)
+   - 2.4 [Optimize List Performance with Stable Object References](#24-optimize-list-performance-with-stable-object-references)
+   - 2.5 [Pass Primitives to List Items for Memoization](#25-pass-primitives-to-list-items-for-memoization)
+   - 2.6 [Use a List Virtualizer for Any List](#26-use-a-list-virtualizer-for-any-list)
+   - 2.7 [Use Compressed Images in Lists](#27-use-compressed-images-in-lists)
+   - 2.8 [Use Item Types for Heterogeneous Lists](#28-use-item-types-for-heterogeneous-lists)
+3. [Animation](#3-animation) — **HIGH**
+   - 3.1 [Animate Transform and Opacity Instead of Layout Properties](#31-animate-transform-and-opacity-instead-of-layout-properties)
+   - 3.2 [Prefer useDerivedValue Over useAnimatedReaction](#32-prefer-usederivedvalue-over-useanimatedreaction)
+   - 3.3 [Use GestureDetector for Animated Press States](#33-use-gesturedetector-for-animated-press-states)
+4. [Scroll Performance](#4-scroll-performance) — **HIGH**
+   - 4.1 [Never Track Scroll Position in useState](#41-never-track-scroll-position-in-usestate)
+5. [Navigation](#5-navigation) — **HIGH**
+   - 5.1 [Use Native Navigators for Navigation](#51-use-native-navigators-for-navigation)
+6. [React State](#6-react-state) — **MEDIUM**
+   - 6.1 [Minimize State Variables and Derive Values](#61-minimize-state-variables-and-derive-values)
+   - 6.2 [Use fallback state instead of initialState](#62-use-fallback-state-instead-of-initialstate)
+   - 6.3 [useState Dispatch updaters for State That Depends on Current Value](#63-usestate-dispatch-updaters-for-state-that-depends-on-current-value)
+7. [State Architecture](#7-state-architecture) — **MEDIUM**
+   - 7.1 [State Must Represent Ground Truth](#71-state-must-represent-ground-truth)
+8. [React Compiler](#8-react-compiler) — **MEDIUM**
+   - 8.1 [Destructure Functions Early in Render (React Compiler)](#81-destructure-functions-early-in-render-react-compiler)
+   - 8.2 [Use .get() and .set() for Reanimated Shared Values (not .value)](#82-use-get-and-set-for-reanimated-shared-values-not-value)
+9. [User Interface](#9-user-interface) — **MEDIUM**
+   - 9.1 [Measuring View Dimensions](#91-measuring-view-dimensions)
+   - 9.2 [Modern React Native Styling Patterns](#92-modern-react-native-styling-patterns)
+   - 9.3 [Use contentInset for Dynamic ScrollView Spacing](#93-use-contentinset-for-dynamic-scrollview-spacing)
+   - 9.4 [Use contentInsetAdjustmentBehavior for Safe Areas](#94-use-contentinsetadjustmentbehavior-for-safe-areas)
+   - 9.5 [Use expo-image for Optimized Images](#95-use-expo-image-for-optimized-images)
+   - 9.6 [Use Galeria for Image Galleries and Lightbox](#96-use-galeria-for-image-galleries-and-lightbox)
+   - 9.7 [Use Native Menus for Dropdowns and Context Menus](#97-use-native-menus-for-dropdowns-and-context-menus)
+   - 9.8 [Use Native Modals Over JS-Based Bottom Sheets](#98-use-native-modals-over-js-based-bottom-sheets)
+   - 9.9 [Use Pressable Instead of Touchable Components](#99-use-pressable-instead-of-touchable-components)
+10. [Design System](#10-design-system) — **MEDIUM**
+   - 10.1 [Use Compound Components Over Polymorphic Children](#101-use-compound-components-over-polymorphic-children)
+11. [Monorepo](#11-monorepo) — **LOW**
+   - 11.1 [Install Native Dependencies in App Directory](#111-install-native-dependencies-in-app-directory)
+   - 11.2 [Use Single Dependency Versions Across Monorepo](#112-use-single-dependency-versions-across-monorepo)
+12. [Third-Party Dependencies](#12-third-party-dependencies) — **LOW**
+   - 12.1 [Import from Design System Folder](#121-import-from-design-system-folder)
+13. [JavaScript](#13-javascript) — **LOW**
+   - 13.1 [Hoist Intl Formatter Creation](#131-hoist-intl-formatter-creation)
+14. [Fonts](#14-fonts) — **LOW**
+   - 14.1 [Load fonts natively at build time](#141-load-fonts-natively-at-build-time)
+
+---
+
+## 1. Core Rendering
+
+**Impact: CRITICAL**
+
+Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+### 1.1 Never Use && with Potentially Falsy Values
+
+**Impact: CRITICAL (prevents production crash)**
+
+Never use `{value && <Component />}` when `value` could be an empty string or
+
+`0`. These are falsy but JSX-renderable—React Native will try to render them as
+
+text outside a `<Text>` component, causing a hard crash in production.
+
+**Incorrect: crashes if count is 0 or name is ""**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name && <Text>{name}</Text>}
+      {count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct: ternary with null**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name ? <Text>{name}</Text> : null}
+      {count ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+**Correct: explicit boolean coercion**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {!!name && <Text>{name}</Text>}
+      {!!count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+```
+
+**Best: early return**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  if (!name) return null
+
+  return (
+    <View>
+      <Text>{name}</Text>
+      {count > 0 ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+
+to catch this automatically.
+
+### 1.2 Wrap Strings in Text Components
+
+**Impact: CRITICAL (prevents runtime crash)**
+
+Strings must be rendered inside `<Text>`. React Native crashes if a string is a
+
+direct child of `<View>`.
+
+**Incorrect: crashes**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return <View>Hello, {name}!</View>
+}
+// Error: Text strings must be rendered within a <Text> component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <View>
+      <Text>Hello, {name}!</Text>
+    </View>
+  )
+}
+```
+
+---
+
+## 2. List Performance
+
+**Impact: HIGH**
+
+Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+### 2.1 Avoid Inline Objects in renderItem
+
+**Impact: HIGH (prevents unnecessary re-renders of memoized list items)**
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+
+create new references on every render, breaking memoization. Pass primitive
+
+values directly from `item` instead.
+
+**Incorrect: inline object breaks memoization**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        <UserRow
+          // Bad: new object on every render
+          user={{ id: item.id, name: item.name, avatar: item.avatar }}
+        />
+      )}
+    />
+  )
+}
+```
+
+**Incorrect: inline style object**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Bad: new style object on every render
+    style={{ backgroundColor: item.isActive ? 'green' : 'gray' }}
+  />
+)}
+```
+
+**Correct: pass item directly or primitives**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        // Good: pass the item directly
+        <UserRow user={item} />
+      )}
+    />
+  )
+}
+```
+
+**Correct: pass primitives, derive inside child**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    id={item.id}
+    name={item.name}
+    isActive={item.isActive}
+  />
+)}
+
+const UserRow = memo(function UserRow({ id, name, isActive }: Props) {
+  // Good: derive style inside memoized component
+  const backgroundColor = isActive ? 'green' : 'gray'
+  return <View style={[styles.row, { backgroundColor }]}>{/* ... */}</View>
+})
+```
+
+**Correct: hoist static styles in module scope**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Good: stable references
+    style={item.isActive ? activeStyle : inactiveStyle}
+  />
+)}
+```
+
+Passing primitives or stable references allows `memo()` to skip re-renders when
+
+the actual values haven't changed.
+
+**Note:** If you have the React Compiler enabled, it handles memoization
+
+automatically and these manual optimizations become less critical.
+
+### 2.2 Hoist callbacks to the root of lists
+
+**Impact: MEDIUM (Fewer re-renders and faster lists)**
+
+When passing callback functions to list items, create a single instance of the
+
+callback at the root of the list. Items should then call it with a unique
+
+identifier.
+
+**Incorrect: creates a new callback on each render**
+
+```typescript
+return (
+  <LegendList
+    renderItem={({ item }) => {
+      // bad: creates a new callback on each render
+      const onPress = () => handlePress(item.id)
+      return <Item key={item.id} item={item} onPress={onPress} />
+    }}
+  />
+)
+```
+
+**Correct: a single function instance passed to each item**
+
+```typescript
+const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id])
+
+return (
+  <LegendList
+    renderItem={({ item }) => (
+      <Item key={item.id} item={item} onPress={onPress} />
+    )}
+  />
+)
+```
+
+Reference: [https://example.com](https://example.com)
+
+### 2.3 Keep List Items Lightweight
+
+**Impact: HIGH (reduces render time for visible items during scroll)**
+
+List items should be as inexpensive as possible to render. Minimize hooks, avoid
+
+queries, and limit React Context access. Virtualized lists render many items
+
+during scroll—expensive items cause jank.
+
+**Incorrect: heavy list item**
+
+```tsx
+function ProductRow({ id }: { id: string }) {
+  // Bad: query inside list item
+  const { data: product } = useQuery(['product', id], () => fetchProduct(id))
+  // Bad: multiple context accesses
+  const theme = useContext(ThemeContext)
+  const user = useContext(UserContext)
+  const cart = useContext(CartContext)
+  // Bad: expensive computation
+  const recommendations = useMemo(
+    () => computeRecommendations(product),
+    [product]
+  )
+
+  return <View>{/* ... */}</View>
+}
+```
+
+**Correct: lightweight list item**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+  // Good: receives only primitives, minimal hooks
+  return (
+    <View>
+      <Image source={{ uri: imageUrl }} />
+      <Text>{name}</Text>
+      <Text>{price}</Text>
+    </View>
+  )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+  const { data: products } = useQuery(['products'], fetchProducts)
+
+  return (
+    <LegendList
+      data={products}
+      renderItem={({ item }) => (
+        <ProductRow name={item.name} price={item.price} imageUrl={item.image} />
+      )}
+    />
+  )
+}
+```
+
+**For shared values, use Zustand selectors instead of Context:**
+
+```tsx
+// Incorrect: Context causes re-render when any cart value changes
+function ProductRow({ id, name }: Props) {
+  const { items } = useContext(CartContext)
+  const inCart = items.includes(id)
+  // ...
+}
+
+// Correct: Zustand selector only re-renders when this specific value changes
+function ProductRow({ id, name }: Props) {
+  // use Set.has (created once at the root) instead of Array.includes()
+  const inCart = useCartStore((s) => s.items.has(id))
+  // ...
+}
+```
+
+**Guidelines for list items:**
+
+- No queries or data fetching
+
+- No expensive computations (move to parent or memoize at parent level)
+
+- Prefer Zustand selectors over React Context
+
+- Minimize useState/useEffect hooks
+
+- Pass pre-computed values as props
+
+The goal: list items should be simple rendering functions that take props and
+
+return JSX.
+
+### 2.4 Optimize List Performance with Stable Object References
+
+**Impact: CRITICAL (virtualization relies on reference stability)**
+
+Don't map or filter data before passing to virtualized lists. Virtualization
+
+relies on object reference stability to know what changed—new references cause
+
+full re-renders of all visible items. Attempt to prevent frequent renders at the
+
+list-parent level.
+
+Where needed, use context selectors within list items.
+
+**Incorrect: creates new object references on every keystroke**
+
+```tsx
+function DomainSearch() {
+  const { keyword, setKeyword } = useKeywordZustandState()
+  const { data: tlds } = useTlds()
+
+  // Bad: creates new objects on every render, reparenting the entire list on every keystroke
+  const domains = tlds.map((tld) => ({
+    domain: `${keyword}.${tld.name}`,
+    tld: tld.name,
+    price: tld.price,
+  }))
+
+  return (
+    <>
+      <TextInput value={keyword} onChangeText={setKeyword} />
+      <LegendList
+        data={domains}
+        renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
+      />
+    </>
+  )
+}
+```
+
+**Correct: stable references, transform inside items**
+
+```tsx
+const renderItem = ({ item }) => <DomainItem tld={item} />
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <LegendList
+      // good: as long as the data is stable, LegendList will not re-render the entire list
+      data={tlds}
+      renderItem={renderItem}
+    />
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // good: transform within items, and don't pass the dynamic data as a prop
+  // good: use a selector function from zustand to receive a stable string back
+  const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
+  return <Text>{domain}</Text>
+}
+```
+
+**Updating parent array reference:**
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return <LegendList data={sortedTlds} renderItem={renderItem} />
+```
+
+Creating a new array instance can be okay, as long as its inner object
+
+references are stable. For instance, if you sort a list of objects:
+
+Even though this creates a new array instance `sortedTlds`, the inner object
+
+references are stable.
+
+**With zustand for dynamic data: avoids parent re-renders**
+
+```tsx
+function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
+  const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
+  return <TldFavoriteButton isFavorited={isFavorited} />
+}
+```
+
+Virtualization can now skip items that haven't changed when typing. Only visible
+
+items (~20) re-render on keystroke, rather than the parent.
+
+**Deriving state within list items based on parent data (avoids parent
+
+re-renders):**
+
+For components where the data is conditional based on the parent state, this
+
+pattern is even more important. For example, if you are checking if an item is
+
+favorited, toggling favorites only re-renders one component if the item itself
+
+is in charge of accessing the state rather than the parent:
+
+Note: if you're using the React Compiler, you can read React Context values
+
+directly within list items. Although this is slightly slower than using a
+
+Zustand selector in most cases, the effect may be negligible.
+
+### 2.5 Pass Primitives to List Items for Memoization
+
+**Impact: HIGH (enables effective memo() comparison)**
+
+When possible, pass only primitive values (strings, numbers, booleans) as props
+
+to list item components. Primitives enable shallow comparison in `memo()` to
+
+work correctly, skipping re-renders when values haven't changed.
+
+**Incorrect: object prop requires deep comparison**
+
+```tsx
+type User = { id: string; name: string; email: string; avatar: string }
+
+const UserRow = memo(function UserRow({ user }: { user: User }) {
+  // memo() compares user by reference, not value
+  // If parent creates new user object, this re-renders even if data is same
+  return <Text>{user.name}</Text>
+})
+
+renderItem={({ item }) => <UserRow user={item} />}
+```
+
+This can still be optimized, but it is harder to memoize properly.
+
+**Correct: primitive props enable shallow comparison**
+
+```tsx
+const UserRow = memo(function UserRow({
+  id,
+  name,
+  email,
+}: {
+  id: string
+  name: string
+  email: string
+}) {
+  // memo() compares each primitive directly
+  // Re-renders only if id, name, or email actually changed
+  return <Text>{name}</Text>
+})
+
+renderItem={({ item }) => (
+  <UserRow id={item.id} name={item.name} email={item.email} />
+)}
+```
+
+**Pass only what you need:**
+
+```tsx
+// Incorrect: passing entire item when you only need name
+<UserRow user={item} />
+
+// Correct: pass only the fields the component uses
+<UserRow name={item.name} avatarUrl={item.avatar} />
+```
+
+**For callbacks, hoist or use item ID:**
+
+```tsx
+// Incorrect: inline function creates new reference
+<UserRow name={item.name} onPress={() => handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+<UserRow id={item.id} name={item.name} />
+
+const UserRow = memo(function UserRow({ id, name }: Props) {
+  const handlePress = useCallback(() => {
+    // use id here
+  }, [id])
+  return <Pressable onPress={handlePress}><Text>{name}</Text></Pressable>
+})
+```
+
+Primitive props make memoization predictable and effective.
+
+**Note:** If you have the React Compiler enabled, you do not need to use
+
+`memo()` or `useCallback()`, but the object references still apply.
+
+### 2.6 Use a List Virtualizer for Any List
+
+**Impact: HIGH (reduced memory, faster mounts)**
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+
+mapped children—even for short lists. Virtualizers only render visible items,
+
+reducing memory usage and mount time. ScrollView renders all children upfront,
+
+which gets expensive quickly.
+
+**Incorrect: ScrollView renders all items at once**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <ScrollView>
+      {items.map((item) => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </ScrollView>
+  )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct: virtualizer renders only visible items**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+      estimatedItemSize={80}
+    />
+  )
+}
+// Only ~10-15 visible items mounted at a time
+```
+
+**Alternative: FlashList**
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <FlashList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+    />
+  )
+}
+```
+
+Benefits apply to any screen with scrollable content—profiles, settings, feeds,
+
+search results. Default to virtualization.
+
+### 2.7 Use Compressed Images in Lists
+
+**Impact: HIGH (faster load times, less memory)**
+
+Always load compressed, appropriately-sized images in lists. Full-resolution
+
+images consume excessive memory and cause scroll jank. Request thumbnails from
+
+your server or use an image CDN with resize parameters.
+
+**Incorrect: full-resolution images**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  return (
+    <View>
+      {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+      <Image
+        source={{ uri: product.imageUrl }}
+        style={{ width: 100, height: 100 }}
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+**Correct: request appropriately-sized image**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  // Request a 200x200 image (2x for retina)
+  const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+  return (
+    <View>
+      <Image
+        source={{ uri: thumbnailUrl }}
+        style={{ width: 100, height: 100 }}
+        contentFit='cover'
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+
+Request images at 2x the display size for retina screens.
+
+### 2.8 Use Item Types for Heterogeneous Lists
+
+**Impact: HIGH (efficient recycling, less layout thrashing)**
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+
+`type` field on each item and provide `getItemType` to the list. This puts items
+
+into separate recycling pools so a message component never gets recycled into an
+
+image component.
+
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
+
+**Incorrect: single component with conditionals**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+  if (item.isHeader) {
+    return <HeaderItem title={item.text} />
+  }
+  if (item.imageUrl) {
+    return <ImageItem url={item.imageUrl} />
+  }
+  return <MessageItem text={item.text} />
+}
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      renderItem={({ item }) => <ListItem item={item} />}
+      recycleItems
+    />
+  )
+}
+```
+
+**Correct: typed items with separate components**
+
+```tsx
+type HeaderItem = { id: string; type: 'header'; title: string }
+type MessageItem = { id: string; type: 'message'; text: string }
+type ImageItem = { id: string; type: 'image'; url: string }
+type FeedItem = HeaderItem | MessageItem | ImageItem
+
+function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <LegendList
+      data={items}
+      keyExtractor={(item) => item.id}
+      getItemType={(item) => item.type}
+      renderItem={({ item }) => {
+        switch (item.type) {
+          case 'header':
+            return <SectionHeader title={item.title} />
+          case 'message':
+            return <MessageRow text={item.text} />
+          case 'image':
+            return <ImageRow url={item.url} />
+        }
+      }}
+      recycleItems
+    />
+  )
+}
+```
+
+**Why this matters:**
+
+```tsx
+<LegendList
+  data={items}
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type}
+  getEstimatedItemSize={(index, item, itemType) => {
+    switch (itemType) {
+      case 'header':
+        return 48
+      case 'message':
+        return 72
+      case 'image':
+        return 300
+      default:
+        return 72
+    }
+  }}
+  renderItem={({ item }) => {
+    /* ... */
+  }}
+  recycleItems
+/>
+```
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+
+- **No layout thrashing**: A header never recycles into an image cell
+
+- **Type safety**: TypeScript can narrow the item type in each branch
+
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+
+  accurate estimates per type
+
+---
+
+## 3. Animation
+
+**Impact: HIGH**
+
+GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+### 3.1 Animate Transform and Opacity Instead of Layout Properties
+
+**Impact: HIGH (GPU-accelerated animations, no layout recalculation)**
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect: animates height, triggers layout every frame**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+    overflow: 'hidden',
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+**Correct: animates scaleY, GPU-accelerated**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scaleY: withTiming(expanded ? 1 : 0) },
+    ],
+    opacity: withTiming(expanded ? 1 : 0),
+  }))
+
+  return (
+    <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>
+      {children}
+    </Animated.View>
+  )
+}
+```
+
+**Correct: animates translateY for slide animations**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: withTiming(visible ? 0 : 100) },
+    ],
+    opacity: withTiming(visible ? 1 : 0),
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
+
+### 3.2 Prefer useDerivedValue Over useAnimatedReaction
+
+**Impact: MEDIUM (cleaner code, automatic dependency tracking)**
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+
+`useAnimatedReaction`. Derived values are declarative, automatically track
+
+dependencies, and return a value you can use directly. Animated reactions are
+
+for side effects, not derivations.
+
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
+
+**Incorrect: useAnimatedReaction for derivation**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct: useDerivedValue**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+### 3.3 Use GestureDetector for Animated Press States
+
+**Impact: MEDIUM (UI thread animations, smoother press feedback)**
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+
+`Gesture.Tap()` and shared values instead of Pressable's
+
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+
+JS thread round-trip for press animations.
+
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
+
+**Incorrect: Pressable with JS thread callbacks**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct: GestureDetector with UI thread worklets**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+---
+
+## 4. Scroll Performance
+
+**Impact: HIGH**
+
+Tracking scroll position without causing render thrashing.
+
+### 4.1 Never Track Scroll Position in useState
+
+**Impact: HIGH (prevents render thrashing during scroll)**
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+
+for animations or a ref for non-reactive tracking.
+
+**Incorrect: useState causes jank**
+
+```tsx
+import { useState } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const [scrollY, setScrollY] = useState(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+**Correct: Reanimated for animations**
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedScrollHandler,
+} from 'react-native-reanimated'
+
+function Feed() {
+  const scrollY = useSharedValue(0)
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollY.value = e.contentOffset.y // runs on UI thread, no re-render
+    },
+  })
+
+  return (
+    <Animated.ScrollView
+      onScroll={onScroll}
+      // higher number has better performance, but it fires less often.
+      // unset this if you need higher precision over performance.
+      scrollEventThrottle={16}
+    />
+  )
+}
+```
+
+**Correct: ref for non-reactive tracking**
+
+```tsx
+import { useRef } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const scrollY = useRef(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+---
+
+## 5. Navigation
+
+**Impact: HIGH**
+
+Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+### 5.1 Use Native Navigators for Navigation
+
+**Impact: HIGH (native performance, platform-appropriate UI)**
+
+Always use native navigators instead of JS-based ones. Native navigators use
+
+platform APIs (UINavigationController on iOS, Fragment on Android) for better
+
+performance and native behavior.
+
+**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+
+stack (which uses native-stack). Avoid `@react-navigation/stack`.
+
+**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+
+tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
+
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
+
+**Incorrect: JS stack navigator**
+
+```tsx
+import { createStackNavigator } from '@react-navigation/stack'
+
+const Stack = createStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct: native stack with react-navigation**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct: expo-router uses native stack by default**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+  return <Stack />
+}
+```
+
+**Incorrect: JS bottom tabs**
+
+```tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
+
+const Tab = createBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name='Home' component={HomeScreen} />
+      <Tab.Screen name='Settings' component={SettingsScreen} />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct: native bottom tabs with react-navigation**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name='Home'
+        component={HomeScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'house' }),
+        }}
+      />
+      <Tab.Screen
+        name='Settings'
+        component={SettingsScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'gear' }),
+        }}
+      />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct: expo-router native tabs**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name='index'>
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name='settings'>
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+
+behind the translucent tab bar. If you need to disable this, use
+
+`disableAutomaticContentInsets` on the trigger.
+
+**Incorrect: custom header component**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    header: () => <CustomHeader title='Profile' />,
+  }}
+/>
+```
+
+**Correct: native header options**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    title: 'Profile',
+    headerLargeTitleEnabled: true,
+    headerSearchBarOptions: {
+      placeholder: 'Search',
+    },
+  }}
+/>
+```
+
+Native headers support iOS large titles, search bars, blur effects, and proper
+
+safe area handling automatically.
+
+- **Performance**: Native transitions and gestures run on the UI thread
+
+- **Platform behavior**: Automatic iOS large titles, Android material design
+
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+
+  areas
+
+- **Accessibility**: Platform accessibility features work automatically
+
+---
+
+## 6. React State
+
+**Impact: MEDIUM**
+
+Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+### 6.1 Minimize State Variables and Derive Values
+
+**Impact: MEDIUM (fewer re-renders, less state drift)**
+
+Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.
+
+**Incorrect: redundant state**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const [total, setTotal] = useState(0)
+  const [itemCount, setItemCount] = useState(0)
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0))
+    setItemCount(items.length)
+  }, [items])
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Correct: derived values**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const total = items.reduce((sum, item) => sum + item.price, 0)
+  const itemCount = items.length
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [https://react.dev/learn/choosing-the-state-structure](https://react.dev/learn/choosing-the-state-structure)
+
+### 6.2 Use fallback state instead of initialState
+
+**Impact: MEDIUM (reactive fallbacks without syncing)**
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+
+parent or server values. State represents user intent only—`undefined` means
+
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+
+source changes, not just on initial render.
+
+**Incorrect: syncs state, loses reactivity**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [enabled, setEnabled] = useState(defaultEnabled)
+  // If fallbackEnabled changes, state is stale
+  // State mixes user intent with default value
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**Correct: state is user intent, reactive fallback**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)
+  const enabled = _enabled ?? defaultEnabled
+  // undefined = user hasn't touched it, falls back to prop
+  // If defaultEnabled changes, component reflects it
+  // Once user interacts, their choice persists
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**With server data:**
+
+```tsx
+function ProfileForm({ data }: { data: User }) {
+  const [_theme, setTheme] = useState<string | undefined>(undefined)
+  const theme = _theme ?? data.theme
+  // Shows server value until user overrides
+  // Server refetch updates the fallback automatically
+
+  return <ThemePicker value={theme} onChange={setTheme} />
+}
+```
+
+### 6.3 useState Dispatch updaters for State That Depends on Current Value
+
+**Impact: MEDIUM (avoids stale closures, prevents unnecessary re-renders)**
+
+When the next state depends on the current state, use a dispatch updater
+
+(`setState(prev => ...)`) instead of reading the state variable directly in a
+
+callback. This avoids stale closures and ensures you're comparing against the
+
+latest value.
+
+**Incorrect: reads state directly**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  // size may be stale in this closure
+  if (size?.width !== width || size?.height !== height) {
+    setSize({ width, height })
+  }
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => {
+    if (prev?.width === width && prev?.height === height) return prev
+    return { width, height }
+  })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+
+re-render.
+
+**Incorrect: unnecessary comparison for primitive state**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct: sets primitive state directly**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+
+dispatch updater.
+
+**Incorrect: reads state directly from the callback**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount(count + 1)
+}
+```
+
+**Correct: dispatch updater**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount((prev) => prev + 1)
+}
+```
+
+---
+
+## 7. State Architecture
+
+**Impact: MEDIUM**
+
+Ground truth principles for state variables and derived values.
+
+### 7.1 State Must Represent Ground Truth
+
+**Impact: HIGH (cleaner logic, easier debugging, single source of truth)**
+
+State variables—both React `useState` and Reanimated shared values—should
+
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+
+visual values from state using computation or interpolation.
+
+**Incorrect: storing the visual output**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    scale.set(withTiming(0.95))
+  })
+  .onFinalize(() => {
+    scale.set(withTiming(1))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct: storing the state, deriving the visual**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    pressed.set(withTiming(1))
+  })
+  .onFinalize(() => {
+    pressed.set(withTiming(0))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+
+   happening; visuals are derived
+
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+
+   requires more interpolations from the same state
+
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+
+   properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+  setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.
+
+---
+
+## 8. React Compiler
+
+**Impact: MEDIUM**
+
+Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+### 8.1 Destructure Functions Early in Render (React Compiler)
+
+**Impact: HIGH (stable references, fewer re-renders)**
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+
+objects to call functions. Destructured functions are stable references; dotting
+
+creates new references and breaks memoization.
+
+**Incorrect: dotting into object**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+  const router = useRouter()
+
+  // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+  const handlePress = () => {
+    props.onSave()
+    router.push('/success') // unstable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+**Correct: destructure early**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+  const { push } = useRouter()
+
+  // good: react-compiler will key on push and onSave
+  const handlePress = () => {
+    onSave()
+    push('/success') // stable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+### 8.2 Use .get() and .set() for Reanimated Shared Values (not .value)
+
+**Impact: LOW (required for React Compiler compatibility)**
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+
+writing `.value` directly on Reanimated shared values. The compiler can't track
+
+property access—explicit methods ensure correct behavior.
+
+**Incorrect: breaks with React Compiler**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.value = count.value + 1 // opts out of react compiler
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.value}`} />
+}
+```
+
+**Correct: React Compiler compatible**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.set(count.get() + 1)
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.get()}`} />
+}
+```
+
+See the
+
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+
+for more.
+
+---
+
+## 9. User Interface
+
+**Impact: MEDIUM**
+
+Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+### 9.1 Measuring View Dimensions
+
+**Impact: MEDIUM (synchronous measurement, avoid unnecessary re-renders)**
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+
+measurement gives you the initial size immediately; `onLayout` keeps it current
+
+when the view changes. For non-primitive states, use a dispatch updater to
+
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [height, setHeight] = useState<number | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    // Sync measurement on mount (RN 0.82+)
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setHeight(rect.height)
+    // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    setHeight(e.nativeEvent.layout.height)
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [size, setSize] = useState<Size | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setSize({ width: rect.width, height: rect.height })
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout
+    setSize((prev) => {
+      // for non-primitive states, compare values before firing a re-render
+      if (prev?.width === width && prev?.height === height) return prev
+      return { width, height }
+    })
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
+
+### 9.2 Modern React Native Styling Patterns
+
+**Impact: MEDIUM (consistent design, smoother borders, cleaner layouts)**
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+<View>
+  <Text style={{ marginBottom: 8 }}>Title</Text>
+  <Text style={{ marginBottom: 8 }}>Subtitle</Text>
+</View>
+
+// Correct – gap on parent
+<View style={{ gap: 8 }}>
+  <Text>Title</Text>
+  <Text>Subtitle</Text>
+</View>
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+<View style={{ padding: 16, gap: 12 }}>
+  <Text>First</Text>
+  <Text>Second</Text>
+</View>
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+<LinearGradient colors={['#000', '#fff']} />
+
+// Correct – native CSS gradient syntax
+<View
+  style={{
+    experimental_backgroundImage: 'linear-gradient(to bottom, #000, #fff)',
+  }}
+/>
+```
+
+**Use CSS `boxShadow` string syntax for shadows:**
+
+```tsx
+// Incorrect – legacy shadow objects or elevation
+{ shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }
+{ elevation: 4 }
+
+// Correct – CSS box-shadow syntax
+{ boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)' }
+```
+
+**Avoid multiple font sizes – use weight and color for emphasis:**
+
+```tsx
+// Incorrect – varying font sizes for hierarchy
+<Text style={{ fontSize: 18 }}>Title</Text>
+<Text style={{ fontSize: 14 }}>Subtitle</Text>
+<Text style={{ fontSize: 12 }}>Caption</Text>
+
+// Correct – consistent size, vary weight and color
+<Text style={{ fontWeight: '600' }}>Title</Text>
+<Text style={{ color: '#666' }}>Subtitle</Text>
+<Text style={{ color: '#999' }}>Caption</Text>
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+
+and grayscale colors for hierarchy instead.
+
+### 9.3 Use contentInset for Dynamic ScrollView Spacing
+
+**Impact: LOW (smoother updates, no layout recalculation)**
+
+When adding space to the top or bottom of a ScrollView that may change
+
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+
+scroll area without re-rendering content.
+
+**Incorrect: padding causes layout recalculation**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView contentContainerStyle={{ paddingBottom: bottomOffset }}>
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct: contentInset for dynamic spacing**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView
+      contentInset={{ bottom: bottomOffset }}
+      scrollIndicatorInsets={{ bottom: bottomOffset }}
+    >
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+
+indicator aligned. For static spacing that never changes, padding is fine.
+
+### 9.4 Use contentInsetAdjustmentBehavior for Safe Areas
+
+**Impact: MEDIUM (native safe area handling, no layout shifts)**
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect: SafeAreaView wrapper**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <ScrollView>
+        <View>
+          <Text>Content</Text>
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+```
+
+**Incorrect: manual safe area padding**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+  const insets = useSafeAreaInsets()
+
+  return (
+    <ScrollView contentContainerStyle={{ paddingTop: insets.top }}>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+**Correct: native content inset adjustment**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <ScrollView contentInsetAdjustmentBehavior='automatic'>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
+
+### 9.5 Use expo-image for Optimized Images
+
+**Impact: HIGH (memory efficiency, caching, blurhash placeholders, progressive loading)**
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect: React Native Image**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**Correct: expo-image**
+
+```tsx
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**With blurhash placeholder:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
+  contentFit="cover"
+  transition={200}
+  style={styles.image}
+/>
+```
+
+**With priority and caching:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  priority="high"
+  cachePolicy="memory-disk"
+  style={styles.hero}
+/>
+```
+
+**Key props:**
+
+- `placeholder` — Blurhash or thumbnail while loading
+
+- `contentFit` — `cover`, `contain`, `fill`, `scale-down`
+
+- `transition` — Fade-in duration (ms)
+
+- `priority` — `low`, `normal`, `high`
+
+- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`
+
+- `recyclingKey` — Unique key for list recycling
+
+For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.
+
+Reference: [https://docs.expo.dev/versions/latest/sdk/image/](https://docs.expo.dev/versions/latest/sdk/image/)
+
+### 9.6 Use Galeria for Image Galleries and Lightbox
+
+**Impact: MEDIUM**
+
+For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.
+
+It provides native shared element transitions with pinch-to-zoom, double-tap
+
+zoom, and pan-to-close. Works with any image component including `expo-image`.
+
+**Incorrect: custom modal implementation**
+
+```tsx
+function ImageGallery({ urls }: { urls: string[] }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <>
+      {urls.map((url) => (
+        <Pressable key={url} onPress={() => setSelected(url)}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Pressable>
+      ))}
+      <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>
+        <Image source={{ uri: selected! }} style={styles.fullscreen} />
+      </Modal>
+    </>
+  )
+}
+```
+
+**Correct: Galeria with expo-image**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+  return (
+    <Galeria urls={urls}>
+      {urls.map((url, index) => (
+        <Galeria.Image index={index} key={url}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Galeria.Image>
+      ))}
+    </Galeria>
+  )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return (
+    <Galeria urls={[url]}>
+      <Galeria.Image>
+        <Image source={{ uri: url }} style={styles.avatar} />
+      </Galeria.Image>
+    </Galeria>
+  )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+<Galeria urls={highResUrls}>
+  {lowResUrls.map((url, index) => (
+    <Galeria.Image index={index} key={url}>
+      <Image source={{ uri: url }} style={styles.thumbnail} />
+    </Galeria.Image>
+  ))}
+</Galeria>
+```
+
+**With FlashList:**
+
+```tsx
+<Galeria urls={urls}>
+  <FlashList
+    data={urls}
+    renderItem={({ item, index }) => (
+      <Galeria.Image index={index}>
+        <Image source={{ uri: item }} style={styles.thumbnail} />
+      </Galeria.Image>
+    )}
+    numColumns={3}
+    estimatedItemSize={100}
+  />
+</Galeria>
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+
+component.
+
+Reference: [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+
+### 9.7 Use Native Menus for Dropdowns and Context Menus
+
+**Impact: HIGH (native accessibility, platform-consistent UX)**
+
+Use native platform menus instead of custom JS implementations. Native menus
+
+provide built-in accessibility, consistent platform UX, and better performance.
+
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect: custom JS menu**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <View>
+      <Pressable onPress={() => setOpen(!open)}>
+        <Text>Open Menu</Text>
+      </Pressable>
+      {open && (
+        <View style={{ position: 'absolute', top: 40 }}>
+          <Pressable onPress={() => console.log('edit')}>
+            <Text>Edit</Text>
+          </Pressable>
+          <Pressable onPress={() => console.log('delete')}>
+            <Text>Delete</Text>
+          </Pressable>
+        </View>
+      )}
+    </View>
+  )
+}
+```
+
+**Correct: native menu with zeego**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Open Menu</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='edit' onSelect={() => console.log('edit')}>
+          <DropdownMenu.ItemTitle>Edit</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Item
+          key='delete'
+          destructive
+          onSelect={() => console.log('delete')}
+        >
+          <DropdownMenu.ItemTitle>Delete</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Context menu: long-press**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <View style={{ padding: 20 }}>
+          <Text>Long press me</Text>
+        </View>
+      </ContextMenu.Trigger>
+
+      <ContextMenu.Content>
+        <ContextMenu.Item key='copy' onSelect={() => console.log('copy')}>
+          <ContextMenu.ItemTitle>Copy</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+
+        <ContextMenu.Item key='paste' onSelect={() => console.log('paste')}>
+          <ContextMenu.ItemTitle>Paste</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+      </ContextMenu.Content>
+    </ContextMenu.Root>
+  )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+  const [notifications, setNotifications] = useState(true)
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Settings</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.CheckboxItem
+          key='notifications'
+          value={notifications}
+          onValueChange={() => setNotifications((prev) => !prev)}
+        >
+          <DropdownMenu.ItemIndicator />
+          <DropdownMenu.ItemTitle>Notifications</DropdownMenu.ItemTitle>
+        </DropdownMenu.CheckboxItem>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Options</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='home' onSelect={() => console.log('home')}>
+          <DropdownMenu.ItemTitle>Home</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Sub>
+          <DropdownMenu.SubTrigger key='more'>
+            <DropdownMenu.ItemTitle>More Options</DropdownMenu.ItemTitle>
+          </DropdownMenu.SubTrigger>
+
+          <DropdownMenu.SubContent>
+            <DropdownMenu.Item key='settings'>
+              <DropdownMenu.ItemTitle>Settings</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+
+            <DropdownMenu.Item key='help'>
+              <DropdownMenu.ItemTitle>Help</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+          </DropdownMenu.SubContent>
+        </DropdownMenu.Sub>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+Reference: [https://zeego.dev/components/dropdown-menu](https://zeego.dev/components/dropdown-menu)
+
+### 9.8 Use Native Modals Over JS-Based Bottom Sheets
+
+**Impact: HIGH (native performance, gestures, accessibility)**
+
+Use native `<Modal>` with `presentationStyle="formSheet"` or React Navigation
+
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+
+have built-in gestures, accessibility, and better performance. Rely on native UI
+
+for low-level primitives.
+
+**Incorrect: JS-based bottom sheet**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+  const sheetRef = useRef<BottomSheet>(null)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => sheetRef.current?.expand()} title='Open' />
+      <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']}>
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </BottomSheet>
+    </View>
+  )
+}
+```
+
+**Correct: native Modal with formSheet**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => setVisible(true)} title='Open' />
+      <Modal
+        visible={visible}
+        presentationStyle='formSheet'
+        animationType='slide'
+        onRequestClose={() => setVisible(false)}
+      >
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </Modal>
+    </View>
+  )
+}
+```
+
+**Correct: React Navigation v7 native form sheet**
+
+```tsx
+// In your navigator
+<Stack.Screen
+  name='Details'
+  component={DetailsScreen}
+  options={{
+    presentation: 'formSheet',
+    sheetAllowedDetents: 'fitToContents',
+  }}
+/>
+```
+
+Native modals provide swipe-to-dismiss, proper keyboard avoidance, and
+
+accessibility out of the box.
+
+### 9.9 Use Pressable Instead of Touchable Components
+
+**Impact: LOW (modern API, more flexible)**
+
+Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from
+
+`react-native` or `react-native-gesture-handler` instead.
+
+**Incorrect: legacy Touchable components**
+
+```tsx
+import { TouchableOpacity } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <TouchableOpacity onPress={onPress} activeOpacity={0.7}>
+      <Text>Press me</Text>
+    </TouchableOpacity>
+  )
+}
+```
+
+**Correct: Pressable**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Press me</Text>
+    </Pressable>
+  )
+}
+```
+
+**Correct: Pressable from gesture handler for lists**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Item</Text>
+    </Pressable>
+  )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+
+gesture coordination, as long as you are using the ScrollView from
+
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+
+with Reanimated shared values instead of Pressable's style callback. See the
+
+`animation-gesture-detector-press` rule.
+
+---
+
+## 10. Design System
+
+**Impact: MEDIUM**
+
+Architecture patterns for building maintainable component
+libraries.
+
+### 10.1 Use Compound Components Over Polymorphic Children
+
+**Impact: MEDIUM (flexible composition, clearer API)**
+
+Don't create components that can accept a string if they aren't a text node. If
+
+a component can receive a string child, it must be a dedicated `*Text`
+
+component. For components like buttons, which can have both a View (or
+
+Pressable) together with text, use compound components, such a `Button`,
+
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect: polymorphic children**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+  children: string | React.ReactNode
+  icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+  return (
+    <Pressable>
+      {icon}
+      {typeof children === 'string' ? <Text>{children}</Text> : children}
+    </Pressable>
+  )
+}
+
+// Usage is ambiguous
+<Button icon={<Icon />}>Save</Button>
+<Button><CustomText>Save</CustomText></Button>
+```
+
+**Correct: compound components**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <Pressable>{children}</Pressable>
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+  return <Text>{children}</Text>
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+  return <>{children}</>
+}
+
+// Usage is explicit and composable
+<Button>
+  <ButtonIcon><SaveIcon /></ButtonIcon>
+  <ButtonText>Save</ButtonText>
+</Button>
+
+<Button>
+  <ButtonText>Cancel</ButtonText>
+</Button>
+```
+
+---
+
+## 11. Monorepo
+
+**Impact: LOW**
+
+Dependency management and native module configuration in
+monorepos.
+
+### 11.1 Install Native Dependencies in App Directory
+
+**Impact: CRITICAL (required for autolinking to work)**
+
+In a monorepo, packages with native code must be installed in the native app's
+
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+
+find native dependencies installed in other packages.
+
+**Incorrect: native dep in shared package only**
+
+```typescript
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct: native dep in app directory**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+
+for autolinking to detect and link the native code.
+
+### 11.2 Use Single Dependency Versions Across Monorepo
+
+**Impact: MEDIUM (avoids duplicate bundles, version conflicts)**
+
+Use a single version of each dependency across all packages in your monorepo.
+
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+
+or npm overrides.
+
+**Incorrect: version ranges, multiple versions**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.0.0"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.5.0"
+  }
+}
+```
+
+**Correct: exact versions, single source of truth**
+
+```json
+// package.json (root)
+{
+  "pnpm": {
+    "overrides": {
+      "react-native-reanimated": "3.16.1"
+    }
+  }
+}
+
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+
+the root. When adding dependencies, specify exact versions without `^` or `~`.
+
+---
+
+## 12. Third-Party Dependencies
+
+**Impact: LOW**
+
+Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+### 12.1 Import from Design System Folder
+
+**Impact: LOW (enables global changes and easy refactoring)**
+
+Re-export dependencies from a design system folder. App code imports from there,
+
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect: imports directly from package**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+**Correct: imports from design system**
+
+```tsx
+import { View } from '@/components/view'
+import { Text } from '@/components/text'
+import { Button } from '@/components/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
+
+---
+
+## 13. JavaScript
+
+**Impact: LOW**
+
+Micro-optimizations like hoisting expensive object creation.
+
+### 13.1 Hoist Intl Formatter Creation
+
+**Impact: LOW-MEDIUM (avoids expensive object recreation)**
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect: new formatter every render**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  })
+  return <Text>{formatter.format(amount)}</Text>
+}
+```
+
+**Correct: hoisted to module scope**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+  return <Text>{currencyFormatter.format(amount)}</Text>
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+  () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+  [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+  numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+
+objects—each instantiation parses locale data and builds internal lookup tables.
+
+---
+
+## 14. Fonts
+
+**Impact: LOW**
+
+Native font loading for improved performance.
+
+### 14.1 Load fonts natively at build time
+
+**Impact: LOW (fonts available at launch, no async loading)**
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
+
+**Incorrect: async font loading**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+  const [fontsLoaded] = useFonts({
+    'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+  })
+
+  if (!fontsLoaded) {
+    return null
+  }
+
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+**Correct: config plugin, fonts embedded at build**
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+  // No loading state needed—font is already available
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+
+native app.
+
+---
+
+## References
+
+1. [https://react.dev](https://react.dev)
+2. [https://reactnative.dev](https://reactnative.dev)
+3. [https://docs.swmansion.com/react-native-reanimated](https://docs.swmansion.com/react-native-reanimated)
+4. [https://docs.swmansion.com/react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler)
+5. [https://docs.expo.dev](https://docs.expo.dev)
+6. [https://legendapp.com/open-source/legend-list](https://legendapp.com/open-source/legend-list)
+7. [https://github.com/nandorojo/galeria](https://github.com/nandorojo/galeria)
+8. [https://zeego.dev](https://zeego.dev)
diff --git a/skills/vercel-react-native-skills/README.md b/skills/vercel-react-native-skills/README.md
new file mode 100644
index 00000000..854db9f5
--- /dev/null
+++ b/skills/vercel-react-native-skills/README.md
@@ -0,0 +1,165 @@
+# React Native Guidelines
+
+A structured repository for creating and maintaining React Native Best Practices
+optimized for agents and LLMs.
+
+## Structure
+
+- `rules/` - Individual rule files (one per rule)
+  - `_sections.md` - Section metadata (titles, impacts, descriptions)
+  - `_template.md` - Template for creating new rules
+  - `area-description.md` - Individual rule files
+- `metadata.json` - Document metadata (version, organization, abstract)
+- **`AGENTS.md`** - Compiled output (generated)
+
+## Rules
+
+### Core Rendering (CRITICAL)
+
+- `rendering-text-in-text-component.md` - Wrap strings in Text components
+- `rendering-no-falsy-and.md` - Avoid falsy && operator in JSX
+
+### List Performance (HIGH)
+
+- `list-performance-virtualize.md` - Use virtualized lists (LegendList,
+  FlashList)
+- `list-performance-function-references.md` - Keep stable object references
+- `list-performance-callbacks.md` - Hoist callbacks to list root
+- `list-performance-inline-objects.md` - Avoid inline objects in renderItem
+- `list-performance-item-memo.md` - Pass primitives for memoization
+- `list-performance-item-expensive.md` - Keep list items lightweight
+- `list-performance-images.md` - Use compressed images in lists
+- `list-performance-item-types.md` - Use item types for heterogeneous lists
+
+### Animation (HIGH)
+
+- `animation-gpu-properties.md` - Animate transform/opacity instead of layout
+- `animation-gesture-detector-press.md` - Use GestureDetector for press
+  animations
+- `animation-derived-value.md` - Prefer useDerivedValue over useAnimatedReaction
+
+### Scroll Performance (HIGH)
+
+- `scroll-position-no-state.md` - Never track scroll in useState
+
+### Navigation (HIGH)
+
+- `navigation-native-navigators.md` - Use native stack and native tabs
+
+### React State (MEDIUM)
+
+- `react-state-dispatcher.md` - Use functional setState updates
+- `react-state-fallback.md` - State should represent user intent only
+- `react-state-minimize.md` - Minimize state variables, derive values
+
+### State Architecture (MEDIUM)
+
+- `state-ground-truth.md` - State must represent ground truth
+
+### React Compiler (MEDIUM)
+
+- `react-compiler-destructure-functions.md` - Destructure functions early
+- `react-compiler-reanimated-shared-values.md` - Use .get()/.set() for shared
+  values
+
+### User Interface (MEDIUM)
+
+- `ui-expo-image.md` - Use expo-image for optimized images
+- `ui-image-gallery.md` - Use Galeria for lightbox/galleries
+- `ui-menus.md` - Native dropdown and context menus with Zeego
+- `ui-native-modals.md` - Use native Modal with formSheet
+- `ui-pressable.md` - Use Pressable instead of TouchableOpacity
+- `ui-measure-views.md` - Measuring view dimensions
+- `ui-safe-area-scroll.md` - Use contentInsetAdjustmentBehavior
+- `ui-scrollview-content-inset.md` - Use contentInset for dynamic spacing
+- `ui-styling.md` - Modern styling patterns (gap, boxShadow, gradients)
+
+### Design System (MEDIUM)
+
+- `design-system-compound-components.md` - Use compound components
+
+### Monorepo (LOW)
+
+- `monorepo-native-deps-in-app.md` - Install native deps in app directory
+- `monorepo-single-dependency-versions.md` - Single dependency versions
+
+### Third-Party Dependencies (LOW)
+
+- `imports-design-system-folder.md` - Import from design system folder
+
+### JavaScript (LOW)
+
+- `js-hoist-intl.md` - Hoist Intl formatter creation
+
+### Fonts (LOW)
+
+- `fonts-config-plugin.md` - Load fonts natively at build time
+
+## Creating a New Rule
+
+1. Copy `rules/_template.md` to `rules/area-description.md`
+2. Choose the appropriate area prefix:
+   - `rendering-` for Core Rendering
+   - `list-performance-` for List Performance
+   - `animation-` for Animation
+   - `scroll-` for Scroll Performance
+   - `navigation-` for Navigation
+   - `react-state-` for React State
+   - `state-` for State Architecture
+   - `react-compiler-` for React Compiler
+   - `ui-` for User Interface
+   - `design-system-` for Design System
+   - `monorepo-` for Monorepo
+   - `imports-` for Third-Party Dependencies
+   - `js-` for JavaScript
+   - `fonts-` for Fonts
+3. Fill in the frontmatter and content
+4. Ensure you have clear examples with explanations
+
+## Rule File Structure
+
+Each rule file should follow this structure:
+
+````markdown
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description
+tags: tag1, tag2, tag3
+---
+
+## Rule Title Here
+
+Brief explanation of the rule and why it matters.
+
+**Incorrect (description of what's wrong):**
+
+```tsx
+// Bad code example
+```
+````
+
+**Correct (description of what's right):**
+
+```tsx
+// Good code example
+```
+
+Reference: [Link](https://example.com)
+
+```
+
+## File Naming Convention
+
+- Files starting with `_` are special (excluded from build)
+- Rule files: `area-description.md` (e.g., `animation-gpu-properties.md`)
+- Section is automatically inferred from filename prefix
+- Rules are sorted alphabetically by title within each section
+
+## Impact Levels
+
+- `CRITICAL` - Highest priority, causes crashes or broken UI
+- `HIGH` - Significant performance improvements
+- `MEDIUM` - Moderate performance improvements
+- `LOW` - Incremental improvements
+```
diff --git a/skills/vercel-react-native-skills/SKILL.md b/skills/vercel-react-native-skills/SKILL.md
new file mode 100644
index 00000000..73401865
--- /dev/null
+++ b/skills/vercel-react-native-skills/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: vercel-react-native-skills
+description:
+  React Native and Expo best practices for building performant mobile apps. Use
+  when building React Native components, optimizing list performance,
+  implementing animations, or working with native modules. Triggers on tasks
+  involving React Native, Expo, mobile performance, or native platform APIs.
+license: MIT
+metadata:
+  author: vercel
+  version: '1.0.0'
+---
+
+# React Native Skills
+
+Comprehensive best practices for React Native and Expo applications. Contains
+rules across multiple categories covering performance, animations, UI patterns,
+and platform-specific optimizations.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Building React Native or Expo apps
+- Optimizing list and scroll performance
+- Implementing animations with Reanimated
+- Working with images and media
+- Configuring native modules or fonts
+- Structuring monorepo projects with native dependencies
+
+## Rule Categories by Priority
+
+| Priority | Category         | Impact   | Prefix               |
+| -------- | ---------------- | -------- | -------------------- |
+| 1        | List Performance | CRITICAL | `list-performance-`  |
+| 2        | Animation        | HIGH     | `animation-`         |
+| 3        | Navigation       | HIGH     | `navigation-`        |
+| 4        | UI Patterns      | HIGH     | `ui-`                |
+| 5        | State Management | MEDIUM   | `react-state-`       |
+| 6        | Rendering        | MEDIUM   | `rendering-`         |
+| 7        | Monorepo         | MEDIUM   | `monorepo-`          |
+| 8        | Configuration    | LOW      | `fonts-`, `imports-` |
+
+## Quick Reference
+
+### 1. List Performance (CRITICAL)
+
+- `list-performance-virtualize` - Use FlashList for large lists
+- `list-performance-item-memo` - Memoize list item components
+- `list-performance-callbacks` - Stabilize callback references
+- `list-performance-inline-objects` - Avoid inline style objects
+- `list-performance-function-references` - Extract functions outside render
+- `list-performance-images` - Optimize images in lists
+- `list-performance-item-expensive` - Move expensive work outside items
+- `list-performance-item-types` - Use item types for heterogeneous lists
+
+### 2. Animation (HIGH)
+
+- `animation-gpu-properties` - Animate only transform and opacity
+- `animation-derived-value` - Use useDerivedValue for computed animations
+- `animation-gesture-detector-press` - Use Gesture.Tap instead of Pressable
+
+### 3. Navigation (HIGH)
+
+- `navigation-native-navigators` - Use native stack and native tabs over JS navigators
+
+### 4. UI Patterns (HIGH)
+
+- `ui-expo-image` - Use expo-image for all images
+- `ui-image-gallery` - Use Galeria for image lightboxes
+- `ui-pressable` - Use Pressable over TouchableOpacity
+- `ui-safe-area-scroll` - Handle safe areas in ScrollViews
+- `ui-scrollview-content-inset` - Use contentInset for headers
+- `ui-menus` - Use native context menus
+- `ui-native-modals` - Use native modals when possible
+- `ui-measure-views` - Use onLayout, not measure()
+- `ui-styling` - Use StyleSheet.create or Nativewind
+
+### 5. State Management (MEDIUM)
+
+- `react-state-minimize` - Minimize state subscriptions
+- `react-state-dispatcher` - Use dispatcher pattern for callbacks
+- `react-state-fallback` - Show fallback on first render
+- `react-compiler-destructure-functions` - Destructure for React Compiler
+- `react-compiler-reanimated-shared-values` - Handle shared values with compiler
+
+### 6. Rendering (MEDIUM)
+
+- `rendering-text-in-text-component` - Wrap text in Text components
+- `rendering-no-falsy-and` - Avoid falsy && for conditional rendering
+
+### 7. Monorepo (MEDIUM)
+
+- `monorepo-native-deps-in-app` - Keep native dependencies in app package
+- `monorepo-single-dependency-versions` - Use single versions across packages
+
+### 8. Configuration (LOW)
+
+- `fonts-config-plugin` - Use config plugins for custom fonts
+- `imports-design-system-folder` - Organize design system imports
+- `js-hoist-intl` - Hoist Intl object creation
+
+## How to Use
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/list-performance-virtualize.md
+rules/animation-gpu-properties.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`
diff --git a/skills/vercel-react-native-skills/metadata.json b/skills/vercel-react-native-skills/metadata.json
new file mode 100644
index 00000000..600eb5bc
--- /dev/null
+++ b/skills/vercel-react-native-skills/metadata.json
@@ -0,0 +1,16 @@
+{
+  "version": "1.0.0",
+  "organization": "Engineering",
+  "date": "January 2026",
+  "abstract": "Comprehensive performance optimization guide for React Native applications, designed for AI agents and LLMs. Contains 35+ rules across 13 categories, prioritized by impact from critical (core rendering, list performance) to incremental (fonts, imports). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.",
+  "references": [
+    "https://react.dev",
+    "https://reactnative.dev",
+    "https://docs.swmansion.com/react-native-reanimated",
+    "https://docs.swmansion.com/react-native-gesture-handler",
+    "https://docs.expo.dev",
+    "https://legendapp.com/open-source/legend-list",
+    "https://github.com/nandorojo/galeria",
+    "https://zeego.dev"
+  ]
+}
diff --git a/skills/vercel-react-native-skills/rules/_sections.md b/skills/vercel-react-native-skills/rules/_sections.md
new file mode 100644
index 00000000..0519cf23
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/_sections.md
@@ -0,0 +1,86 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Core Rendering (rendering)
+
+**Impact:** CRITICAL  
+**Description:** Fundamental React Native rendering rules. Violations cause
+runtime crashes or broken UI.
+
+## 2. List Performance (list-performance)
+
+**Impact:** HIGH  
+**Description:** Optimizing virtualized lists (FlatList, LegendList, FlashList)
+for smooth scrolling and fast updates.
+
+## 3. Animation (animation)
+
+**Impact:** HIGH  
+**Description:** GPU-accelerated animations, Reanimated patterns, and avoiding
+render thrashing during gestures.
+
+## 4. Scroll Performance (scroll)
+
+**Impact:** HIGH  
+**Description:** Tracking scroll position without causing render thrashing.
+
+## 5. Navigation (navigation)
+
+**Impact:** HIGH  
+**Description:** Using native navigators for stack and tab navigation instead of
+JS-based alternatives.
+
+## 6. React State (react-state)
+
+**Impact:** MEDIUM  
+**Description:** Patterns for managing React state to avoid stale closures and
+unnecessary re-renders.
+
+## 7. State Architecture (state)
+
+**Impact:** MEDIUM  
+**Description:** Ground truth principles for state variables and derived values.
+
+## 8. React Compiler (react-compiler)
+
+**Impact:** MEDIUM  
+**Description:** Compatibility patterns for React Compiler with React Native and
+Reanimated.
+
+## 9. User Interface (ui)
+
+**Impact:** MEDIUM  
+**Description:** Native UI patterns for images, menus, modals, styling, and
+platform-consistent interfaces.
+
+## 10. Design System (design-system)
+
+**Impact:** MEDIUM  
+**Description:** Architecture patterns for building maintainable component
+libraries.
+
+## 11. Monorepo (monorepo)
+
+**Impact:** LOW  
+**Description:** Dependency management and native module configuration in
+monorepos.
+
+## 12. Third-Party Dependencies (imports)
+
+**Impact:** LOW  
+**Description:** Wrapping and re-exporting third-party dependencies for
+maintainability.
+
+## 13. JavaScript (js)
+
+**Impact:** LOW  
+**Description:** Micro-optimizations like hoisting expensive object creation.
+
+## 14. Fonts (fonts)
+
+**Impact:** LOW  
+**Description:** Native font loading for improved performance.
diff --git a/skills/vercel-react-native-skills/rules/_template.md b/skills/vercel-react-native-skills/rules/_template.md
new file mode 100644
index 00000000..1e9e7070
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/_template.md
@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel-react-native-skills/rules/animation-derived-value.md b/skills/vercel-react-native-skills/rules/animation-derived-value.md
new file mode 100644
index 00000000..310928a9
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-derived-value.md
@@ -0,0 +1,53 @@
+---
+title: Prefer useDerivedValue Over useAnimatedReaction
+impact: MEDIUM
+impactDescription: cleaner code, automatic dependency tracking
+tags: animation, reanimated, derived-value
+---
+
+## Prefer useDerivedValue Over useAnimatedReaction
+
+When deriving a shared value from another, use `useDerivedValue` instead of
+`useAnimatedReaction`. Derived values are declarative, automatically track
+dependencies, and return a value you can use directly. Animated reactions are
+for side effects, not derivations.
+
+**Incorrect (useAnimatedReaction for derivation):**
+
+```tsx
+import { useSharedValue, useAnimatedReaction } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+  const opacity = useSharedValue(1)
+
+  useAnimatedReaction(
+    () => progress.value,
+    (current) => {
+      opacity.value = 1 - current
+    }
+  )
+
+  // ...
+}
+```
+
+**Correct (useDerivedValue):**
+
+```tsx
+import { useSharedValue, useDerivedValue } from 'react-native-reanimated'
+
+function MyComponent() {
+  const progress = useSharedValue(0)
+
+  const opacity = useDerivedValue(() => 1 - progress.get())
+
+  // ...
+}
+```
+
+Use `useAnimatedReaction` only for side effects that don't produce a value
+(e.g., triggering haptics, logging, calling `runOnJS`).
+
+Reference:
+[Reanimated useDerivedValue](https://docs.swmansion.com/react-native-reanimated/docs/core/useDerivedValue)
diff --git a/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md b/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md
new file mode 100644
index 00000000..87c67827
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-gesture-detector-press.md
@@ -0,0 +1,95 @@
+---
+title: Use GestureDetector for Animated Press States
+impact: MEDIUM
+impactDescription: UI thread animations, smoother press feedback
+tags: animation, gestures, press, reanimated
+---
+
+## Use GestureDetector for Animated Press States
+
+For animated press states (scale, opacity on press), use `GestureDetector` with
+`Gesture.Tap()` and shared values instead of Pressable's
+`onPressIn`/`onPressOut`. Gesture callbacks run on the UI thread as worklets—no
+JS thread round-trip for press animations.
+
+**Incorrect (Pressable with JS thread callbacks):**
+
+```tsx
+import { Pressable } from 'react-native'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  const scale = useSharedValue(1)
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ scale: scale.value }],
+  }))
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => (scale.value = withTiming(0.95))}
+      onPressOut={() => (scale.value = withTiming(1))}
+    >
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </Pressable>
+  )
+}
+```
+
+**Correct (GestureDetector with UI thread worklets):**
+
+```tsx
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withTiming,
+  interpolate,
+  runOnJS,
+} from 'react-native-reanimated'
+
+function AnimatedButton({ onPress }: { onPress: () => void }) {
+  // Store the press STATE (0 = not pressed, 1 = pressed)
+  const pressed = useSharedValue(0)
+
+  const tap = Gesture.Tap()
+    .onBegin(() => {
+      pressed.set(withTiming(1))
+    })
+    .onFinalize(() => {
+      pressed.set(withTiming(0))
+    })
+    .onEnd(() => {
+      runOnJS(onPress)()
+    })
+
+  // Derive visual values from the state
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scale: interpolate(withTiming(pressed.get()), [0, 1], [1, 0.95]) },
+    ],
+  }))
+
+  return (
+    <GestureDetector gesture={tap}>
+      <Animated.View style={animatedStyle}>
+        <Text>Press me</Text>
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+```
+
+Store the press **state** (0 or 1), then derive the scale via `interpolate`.
+This keeps the shared value as ground truth. Use `runOnJS` to call JS functions
+from worklets. Use `.set()` and `.get()` for React Compiler compatibility.
+
+Reference:
+[Gesture Handler Tap Gesture](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture)
diff --git a/skills/vercel-react-native-skills/rules/animation-gpu-properties.md b/skills/vercel-react-native-skills/rules/animation-gpu-properties.md
new file mode 100644
index 00000000..5fda0955
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/animation-gpu-properties.md
@@ -0,0 +1,65 @@
+---
+title: Animate Transform and Opacity Instead of Layout Properties
+impact: HIGH
+impactDescription: GPU-accelerated animations, no layout recalculation
+tags: animation, performance, reanimated, transform, opacity
+---
+
+## Animate Transform and Opacity Instead of Layout Properties
+
+Avoid animating `width`, `height`, `top`, `left`, `margin`, or `padding`. These trigger layout recalculation on every frame. Instead, use `transform` (scale, translate) and `opacity` which run on the GPU without triggering layout.
+
+**Incorrect (animates height, triggers layout every frame):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    height: withTiming(expanded ? 200 : 0), // triggers layout on every frame
+    overflow: 'hidden',
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+**Correct (animates scaleY, GPU-accelerated):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function CollapsiblePanel({ expanded }: { expanded: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { scaleY: withTiming(expanded ? 1 : 0) },
+    ],
+    opacity: withTiming(expanded ? 1 : 0),
+  }))
+
+  return (
+    <Animated.View style={[{ height: 200, transformOrigin: 'top' }, animatedStyle]}>
+      {children}
+    </Animated.View>
+  )
+}
+```
+
+**Correct (animates translateY for slide animations):**
+
+```tsx
+import Animated, { useAnimatedStyle, withTiming } from 'react-native-reanimated'
+
+function SlideIn({ visible }: { visible: boolean }) {
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateY: withTiming(visible ? 0 : 100) },
+    ],
+    opacity: withTiming(visible ? 1 : 0),
+  }))
+
+  return <Animated.View style={animatedStyle}>{children}</Animated.View>
+}
+```
+
+GPU-accelerated properties: `transform` (translate, scale, rotate), `opacity`. Everything else triggers layout.
diff --git a/skills/vercel-react-native-skills/rules/design-system-compound-components.md b/skills/vercel-react-native-skills/rules/design-system-compound-components.md
new file mode 100644
index 00000000..d8239ee1
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/design-system-compound-components.md
@@ -0,0 +1,66 @@
+---
+title: Use Compound Components Over Polymorphic Children
+impact: MEDIUM
+impactDescription: flexible composition, clearer API
+tags: design-system, components, composition
+---
+
+## Use Compound Components Over Polymorphic Children
+
+Don't create components that can accept a string if they aren't a text node. If
+a component can receive a string child, it must be a dedicated `*Text`
+component. For components like buttons, which can have both a View (or
+Pressable) together with text, use compound components, such a `Button`,
+`ButtonText`, and `ButtonIcon`.
+
+**Incorrect (polymorphic children):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+type ButtonProps = {
+  children: string | React.ReactNode
+  icon?: React.ReactNode
+}
+
+function Button({ children, icon }: ButtonProps) {
+  return (
+    <Pressable>
+      {icon}
+      {typeof children === 'string' ? <Text>{children}</Text> : children}
+    </Pressable>
+  )
+}
+
+// Usage is ambiguous
+<Button icon={<Icon />}>Save</Button>
+<Button><CustomText>Save</CustomText></Button>
+```
+
+**Correct (compound components):**
+
+```tsx
+import { Pressable, Text } from 'react-native'
+
+function Button({ children }: { children: React.ReactNode }) {
+  return <Pressable>{children}</Pressable>
+}
+
+function ButtonText({ children }: { children: React.ReactNode }) {
+  return <Text>{children}</Text>
+}
+
+function ButtonIcon({ children }: { children: React.ReactNode }) {
+  return <>{children}</>
+}
+
+// Usage is explicit and composable
+<Button>
+  <ButtonIcon><SaveIcon /></ButtonIcon>
+  <ButtonText>Save</ButtonText>
+</Button>
+
+<Button>
+  <ButtonText>Cancel</ButtonText>
+</Button>
+```
diff --git a/skills/vercel-react-native-skills/rules/fonts-config-plugin.md b/skills/vercel-react-native-skills/rules/fonts-config-plugin.md
new file mode 100644
index 00000000..39aa0147
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/fonts-config-plugin.md
@@ -0,0 +1,71 @@
+---
+title: Load fonts natively at build time
+impact: LOW
+impactDescription: fonts available at launch, no async loading
+tags: fonts, expo, performance, config-plugin
+---
+
+## Use Expo Config Plugin for Font Loading
+
+Use the `expo-font` config plugin to embed fonts at build time instead of
+`useFonts` or `Font.loadAsync`. Embedded fonts are more efficient.
+
+**Incorrect (async font loading):**
+
+```tsx
+import { useFonts } from 'expo-font'
+import { Text, View } from 'react-native'
+
+function App() {
+  const [fontsLoaded] = useFonts({
+    'Geist-Bold': require('./assets/fonts/Geist-Bold.otf'),
+  })
+
+  if (!fontsLoaded) {
+    return null
+  }
+
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+**Correct (config plugin, fonts embedded at build):**
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-font",
+        {
+          "fonts": ["./assets/fonts/Geist-Bold.otf"]
+        }
+      ]
+    ]
+  }
+}
+```
+
+```tsx
+import { Text, View } from 'react-native'
+
+function App() {
+  // No loading state needed—font is already available
+  return (
+    <View>
+      <Text style={{ fontFamily: 'Geist-Bold' }}>Hello</Text>
+    </View>
+  )
+}
+```
+
+After adding fonts to the config plugin, run `npx expo prebuild` and rebuild the
+native app.
+
+Reference:
+[Expo Font Documentation](https://docs.expo.dev/versions/latest/sdk/font/)
diff --git a/skills/vercel-react-native-skills/rules/imports-design-system-folder.md b/skills/vercel-react-native-skills/rules/imports-design-system-folder.md
new file mode 100644
index 00000000..8466dcb2
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/imports-design-system-folder.md
@@ -0,0 +1,68 @@
+---
+title: Import from Design System Folder
+impact: LOW
+impactDescription: enables global changes and easy refactoring
+tags: imports, architecture, design-system
+---
+
+## Import from Design System Folder
+
+Re-export dependencies from a design system folder. App code imports from there,
+not directly from packages. This enables global changes and easy refactoring.
+
+**Incorrect (imports directly from package):**
+
+```tsx
+import { View, Text } from 'react-native'
+import { Button } from '@ui/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+**Correct (imports from design system):**
+
+```tsx
+// components/view.tsx
+import { View as RNView } from 'react-native'
+
+// ideal: pick the props you will actually use to control implementation
+export function View(
+  props: Pick<React.ComponentProps<typeof RNView>, 'style' | 'children'>
+) {
+  return <RNView {...props} />
+}
+```
+
+```tsx
+// components/text.tsx
+export { Text } from 'react-native'
+```
+
+```tsx
+// components/button.tsx
+export { Button } from '@ui/button'
+```
+
+```tsx
+import { View } from '@/components/view'
+import { Text } from '@/components/text'
+import { Button } from '@/components/button'
+
+function Profile() {
+  return (
+    <View>
+      <Text>Hello</Text>
+      <Button>Save</Button>
+    </View>
+  )
+}
+```
+
+Start by simply re-exporting. Customize later without changing app code.
diff --git a/skills/vercel-react-native-skills/rules/js-hoist-intl.md b/skills/vercel-react-native-skills/rules/js-hoist-intl.md
new file mode 100644
index 00000000..9af1c354
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/js-hoist-intl.md
@@ -0,0 +1,61 @@
+---
+title: Hoist Intl Formatter Creation
+impact: LOW-MEDIUM
+impactDescription: avoids expensive object recreation
+tags: javascript, intl, optimization, memoization
+---
+
+## Hoist Intl Formatter Creation
+
+Don't create `Intl.DateTimeFormat`, `Intl.NumberFormat`, or
+`Intl.RelativeTimeFormat` inside render or loops. These are expensive to
+instantiate. Hoist to module scope when the locale/options are static.
+
+**Incorrect (new formatter every render):**
+
+```tsx
+function Price({ amount }: { amount: number }) {
+  const formatter = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  })
+  return <Text>{formatter.format(amount)}</Text>
+}
+```
+
+**Correct (hoisted to module scope):**
+
+```tsx
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+})
+
+function Price({ amount }: { amount: number }) {
+  return <Text>{currencyFormatter.format(amount)}</Text>
+}
+```
+
+**For dynamic locales, memoize:**
+
+```tsx
+const dateFormatter = useMemo(
+  () => new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }),
+  [locale]
+)
+```
+
+**Common formatters to hoist:**
+
+```tsx
+// Module-level formatters
+const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' })
+const timeFormatter = new Intl.DateTimeFormat('en-US', { timeStyle: 'short' })
+const percentFormatter = new Intl.NumberFormat('en-US', { style: 'percent' })
+const relativeFormatter = new Intl.RelativeTimeFormat('en-US', {
+  numeric: 'auto',
+})
+```
+
+Creating `Intl` objects is significantly more expensive than `RegExp` or plain
+objects—each instantiation parses locale data and builds internal lookup tables.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-callbacks.md b/skills/vercel-react-native-skills/rules/list-performance-callbacks.md
new file mode 100644
index 00000000..a0b3913f
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-callbacks.md
@@ -0,0 +1,44 @@
+---
+title: Hoist callbacks to the root of lists
+impact: MEDIUM
+impactDescription: Fewer re-renders and faster lists
+tags: tag1, tag2
+---
+
+## List performance callbacks
+
+**Impact: HIGH (Fewer re-renders and faster lists)**
+
+When passing callback functions to list items, create a single instance of the
+callback at the root of the list. Items should then call it with a unique
+identifier.
+
+**Incorrect (creates a new callback on each render):**
+
+```typescript
+return (
+  <LegendList
+    renderItem={({ item }) => {
+      // bad: creates a new callback on each render
+      const onPress = () => handlePress(item.id)
+      return <Item key={item.id} item={item} onPress={onPress} />
+    }}
+  />
+)
+```
+
+**Correct (a single function instance passed to each item):**
+
+```typescript
+const onPress = useCallback(() => handlePress(item.id), [handlePress, item.id])
+
+return (
+  <LegendList
+    renderItem={({ item }) => (
+      <Item key={item.id} item={item} onPress={onPress} />
+    )}
+  />
+)
+```
+
+Reference: [Link to documentation or resource](https://example.com)
diff --git a/skills/vercel-react-native-skills/rules/list-performance-function-references.md b/skills/vercel-react-native-skills/rules/list-performance-function-references.md
new file mode 100644
index 00000000..9721929b
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-function-references.md
@@ -0,0 +1,132 @@
+---
+title: Optimize List Performance with Stable Object References
+impact: CRITICAL
+impactDescription: virtualization relies on reference stability
+tags: lists, performance, flatlist, virtualization
+---
+
+## Optimize List Performance with Stable Object References
+
+Don't map or filter data before passing to virtualized lists. Virtualization
+relies on object reference stability to know what changed—new references cause
+full re-renders of all visible items. Attempt to prevent frequent renders at the
+list-parent level.
+
+Where needed, use context selectors within list items.
+
+**Incorrect (creates new object references on every keystroke):**
+
+```tsx
+function DomainSearch() {
+  const { keyword, setKeyword } = useKeywordZustandState()
+  const { data: tlds } = useTlds()
+
+  // Bad: creates new objects on every render, reparenting the entire list on every keystroke
+  const domains = tlds.map((tld) => ({
+    domain: `${keyword}.${tld.name}`,
+    tld: tld.name,
+    price: tld.price,
+  }))
+
+  return (
+    <>
+      <TextInput value={keyword} onChangeText={setKeyword} />
+      <LegendList
+        data={domains}
+        renderItem={({ item }) => <DomainItem item={item} keyword={keyword} />}
+      />
+    </>
+  )
+}
+```
+
+**Correct (stable references, transform inside items):**
+
+```tsx
+const renderItem = ({ item }) => <DomainItem tld={item} />
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <LegendList
+      // good: as long as the data is stable, LegendList will not re-render the entire list
+      data={tlds}
+      renderItem={renderItem}
+    />
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // good: transform within items, and don't pass the dynamic data as a prop
+  // good: use a selector function from zustand to receive a stable string back
+  const domain = useKeywordZustandState((s) => s.keyword + '.' + tld.name)
+  return <Text>{domain}</Text>
+}
+```
+
+**Updating parent array reference:**
+
+Creating a new array instance can be okay, as long as its inner object
+references are stable. For instance, if you sort a list of objects:
+
+```tsx
+// good: creates a new array instance without mutating the inner objects
+// good: parent array reference is unaffected by typing and updating "keyword"
+const sortedTlds = tlds.toSorted((a, b) => a.name.localeCompare(b.name))
+
+return <LegendList data={sortedTlds} renderItem={renderItem} />
+```
+
+Even though this creates a new array instance `sortedTlds`, the inner object
+references are stable.
+
+**With zustand for dynamic data (avoids parent re-renders):**
+
+```tsx
+const useSearchStore = create<{ keyword: string }>(() => ({ keyword: '' }))
+
+function DomainSearch() {
+  const { data: tlds } = useTlds()
+
+  return (
+    <>
+      <SearchInput />
+      <LegendList
+        data={tlds}
+        // if you aren't using React Compiler, wrap renderItem with useCallback
+        renderItem={({ item }) => <DomainItem tld={item} />}
+      />
+    </>
+  )
+}
+
+function DomainItem({ tld }: { tld: Tld }) {
+  // Select only what you need—component only re-renders when keyword changes
+  const keyword = useSearchStore((s) => s.keyword)
+  const domain = `${keyword}.${tld.name}`
+  return <Text>{domain}</Text>
+}
+```
+
+Virtualization can now skip items that haven't changed when typing. Only visible
+items (~20) re-render on keystroke, rather than the parent.
+
+**Deriving state within list items based on parent data (avoids parent
+re-renders):**
+
+For components where the data is conditional based on the parent state, this
+pattern is even more important. For example, if you are checking if an item is
+favorited, toggling favorites only re-renders one component if the item itself
+is in charge of accessing the state rather than the parent:
+
+```tsx
+function DomainItemFavoriteButton({ tld }: { tld: Tld }) {
+  const isFavorited = useFavoritesStore((s) => s.favorites.has(tld.id))
+  return <TldFavoriteButton isFavorited={isFavorited} />
+}
+```
+
+Note: if you're using the React Compiler, you can read React Context values
+directly within list items. Although this is slightly slower than using a
+Zustand selector in most cases, the effect may be negligible.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-images.md b/skills/vercel-react-native-skills/rules/list-performance-images.md
new file mode 100644
index 00000000..75a3bafc
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-images.md
@@ -0,0 +1,53 @@
+---
+title: Use Compressed Images in Lists
+impact: HIGH
+impactDescription: faster load times, less memory
+tags: lists, images, performance, optimization
+---
+
+## Use Compressed Images in Lists
+
+Always load compressed, appropriately-sized images in lists. Full-resolution
+images consume excessive memory and cause scroll jank. Request thumbnails from
+your server or use an image CDN with resize parameters.
+
+**Incorrect (full-resolution images):**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  return (
+    <View>
+      {/* 4000x3000 image loaded for a 100x100 thumbnail */}
+      <Image
+        source={{ uri: product.imageUrl }}
+        style={{ width: 100, height: 100 }}
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+**Correct (request appropriately-sized image):**
+
+```tsx
+function ProductItem({ product }: { product: Product }) {
+  // Request a 200x200 image (2x for retina)
+  const thumbnailUrl = `${product.imageUrl}?w=200&h=200&fit=cover`
+
+  return (
+    <View>
+      <Image
+        source={{ uri: thumbnailUrl }}
+        style={{ width: 100, height: 100 }}
+        contentFit='cover'
+      />
+      <Text>{product.name}</Text>
+    </View>
+  )
+}
+```
+
+Use an optimized image component with built-in caching and placeholder support,
+such as `expo-image` or `SolitoImage` (which uses `expo-image` under the hood).
+Request images at 2x the display size for retina screens.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md b/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md
new file mode 100644
index 00000000..d5b6514a
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-inline-objects.md
@@ -0,0 +1,97 @@
+---
+title: Avoid Inline Objects in renderItem
+impact: HIGH
+impactDescription: prevents unnecessary re-renders of memoized list items
+tags: lists, performance, flatlist, virtualization, memo
+---
+
+## Avoid Inline Objects in renderItem
+
+Don't create new objects inside `renderItem` to pass as props. Inline objects
+create new references on every render, breaking memoization. Pass primitive
+values directly from `item` instead.
+
+**Incorrect (inline object breaks memoization):**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        <UserRow
+          // Bad: new object on every render
+          user={{ id: item.id, name: item.name, avatar: item.avatar }}
+        />
+      )}
+    />
+  )
+}
+```
+
+**Incorrect (inline style object):**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Bad: new style object on every render
+    style={{ backgroundColor: item.isActive ? 'green' : 'gray' }}
+  />
+)}
+```
+
+**Correct (pass item directly or primitives):**
+
+```tsx
+function UserList({ users }: { users: User[] }) {
+  return (
+    <LegendList
+      data={users}
+      renderItem={({ item }) => (
+        // Good: pass the item directly
+        <UserRow user={item} />
+      )}
+    />
+  )
+}
+```
+
+**Correct (pass primitives, derive inside child):**
+
+```tsx
+renderItem={({ item }) => (
+  <UserRow
+    id={item.id}
+    name={item.name}
+    isActive={item.isActive}
+  />
+)}
+
+const UserRow = memo(function UserRow({ id, name, isActive }: Props) {
+  // Good: derive style inside memoized component
+  const backgroundColor = isActive ? 'green' : 'gray'
+  return <View style={[styles.row, { backgroundColor }]}>{/* ... */}</View>
+})
+```
+
+**Correct (hoist static styles in module scope):**
+
+```tsx
+const activeStyle = { backgroundColor: 'green' }
+const inactiveStyle = { backgroundColor: 'gray' }
+
+renderItem={({ item }) => (
+  <UserRow
+    name={item.name}
+    // Good: stable references
+    style={item.isActive ? activeStyle : inactiveStyle}
+  />
+)}
+```
+
+Passing primitives or stable references allows `memo()` to skip re-renders when
+the actual values haven't changed.
+
+**Note:** If you have the React Compiler enabled, it handles memoization
+automatically and these manual optimizations become less critical.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-item-expensive.md b/skills/vercel-react-native-skills/rules/list-performance-item-expensive.md
new file mode 100644
index 00000000..f617a76d
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-item-expensive.md
@@ -0,0 +1,94 @@
+---
+title: Keep List Items Lightweight
+impact: HIGH
+impactDescription: reduces render time for visible items during scroll
+tags: lists, performance, virtualization, hooks
+---
+
+## Keep List Items Lightweight
+
+List items should be as inexpensive as possible to render. Minimize hooks, avoid
+queries, and limit React Context access. Virtualized lists render many items
+during scroll—expensive items cause jank.
+
+**Incorrect (heavy list item):**
+
+```tsx
+function ProductRow({ id }: { id: string }) {
+  // Bad: query inside list item
+  const { data: product } = useQuery(['product', id], () => fetchProduct(id))
+  // Bad: multiple context accesses
+  const theme = useContext(ThemeContext)
+  const user = useContext(UserContext)
+  const cart = useContext(CartContext)
+  // Bad: expensive computation
+  const recommendations = useMemo(
+    () => computeRecommendations(product),
+    [product]
+  )
+
+  return <View>{/* ... */}</View>
+}
+```
+
+**Correct (lightweight list item):**
+
+```tsx
+function ProductRow({ name, price, imageUrl }: Props) {
+  // Good: receives only primitives, minimal hooks
+  return (
+    <View>
+      <Image source={{ uri: imageUrl }} />
+      <Text>{name}</Text>
+      <Text>{price}</Text>
+    </View>
+  )
+}
+```
+
+**Move data fetching to parent:**
+
+```tsx
+// Parent fetches all data once
+function ProductList() {
+  const { data: products } = useQuery(['products'], fetchProducts)
+
+  return (
+    <LegendList
+      data={products}
+      renderItem={({ item }) => (
+        <ProductRow name={item.name} price={item.price} imageUrl={item.image} />
+      )}
+    />
+  )
+}
+```
+
+**For shared values, use Zustand selectors instead of Context:**
+
+```tsx
+// Incorrect: Context causes re-render when any cart value changes
+function ProductRow({ id, name }: Props) {
+  const { items } = useContext(CartContext)
+  const inCart = items.includes(id)
+  // ...
+}
+
+// Correct: Zustand selector only re-renders when this specific value changes
+function ProductRow({ id, name }: Props) {
+  // use Set.has (created once at the root) instead of Array.includes()
+  const inCart = useCartStore((s) => s.items.has(id))
+  // ...
+}
+```
+
+**Guidelines for list items:**
+
+- No queries or data fetching
+- No expensive computations (move to parent or memoize at parent level)
+- Prefer Zustand selectors over React Context
+- Minimize useState/useEffect hooks
+- Pass pre-computed values as props
+
+The goal: list items should be simple rendering functions that take props and
+return JSX.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-item-memo.md b/skills/vercel-react-native-skills/rules/list-performance-item-memo.md
new file mode 100644
index 00000000..634935e8
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-item-memo.md
@@ -0,0 +1,82 @@
+---
+title: Pass Primitives to List Items for Memoization
+impact: HIGH
+impactDescription: enables effective memo() comparison
+tags: lists, performance, memo, primitives
+---
+
+## Pass Primitives to List Items for Memoization
+
+When possible, pass only primitive values (strings, numbers, booleans) as props
+to list item components. Primitives enable shallow comparison in `memo()` to
+work correctly, skipping re-renders when values haven't changed.
+
+**Incorrect (object prop requires deep comparison):**
+
+```tsx
+type User = { id: string; name: string; email: string; avatar: string }
+
+const UserRow = memo(function UserRow({ user }: { user: User }) {
+  // memo() compares user by reference, not value
+  // If parent creates new user object, this re-renders even if data is same
+  return <Text>{user.name}</Text>
+})
+
+renderItem={({ item }) => <UserRow user={item} />}
+```
+
+This can still be optimized, but it is harder to memoize properly.
+
+**Correct (primitive props enable shallow comparison):**
+
+```tsx
+const UserRow = memo(function UserRow({
+  id,
+  name,
+  email,
+}: {
+  id: string
+  name: string
+  email: string
+}) {
+  // memo() compares each primitive directly
+  // Re-renders only if id, name, or email actually changed
+  return <Text>{name}</Text>
+})
+
+renderItem={({ item }) => (
+  <UserRow id={item.id} name={item.name} email={item.email} />
+)}
+```
+
+**Pass only what you need:**
+
+```tsx
+// Incorrect: passing entire item when you only need name
+<UserRow user={item} />
+
+// Correct: pass only the fields the component uses
+<UserRow name={item.name} avatarUrl={item.avatar} />
+```
+
+**For callbacks, hoist or use item ID:**
+
+```tsx
+// Incorrect: inline function creates new reference
+<UserRow name={item.name} onPress={() => handlePress(item.id)} />
+
+// Correct: pass ID, handle in child
+<UserRow id={item.id} name={item.name} />
+
+const UserRow = memo(function UserRow({ id, name }: Props) {
+  const handlePress = useCallback(() => {
+    // use id here
+  }, [id])
+  return <Pressable onPress={handlePress}><Text>{name}</Text></Pressable>
+})
+```
+
+Primitive props make memoization predictable and effective.
+
+**Note:** If you have the React Compiler enabled, you do not need to use
+`memo()` or `useCallback()`, but the object references still apply.
diff --git a/skills/vercel-react-native-skills/rules/list-performance-item-types.md b/skills/vercel-react-native-skills/rules/list-performance-item-types.md
new file mode 100644
index 00000000..1027e4e6
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-item-types.md
@@ -0,0 +1,104 @@
+---
+title: Use Item Types for Heterogeneous Lists
+impact: HIGH
+impactDescription: efficient recycling, less layout thrashing
+tags: list, performance, recycling, heterogeneous, LegendList
+---
+
+## Use Item Types for Heterogeneous Lists
+
+When a list has different item layouts (messages, images, headers, etc.), use a
+`type` field on each item and provide `getItemType` to the list. This puts items
+into separate recycling pools so a message component never gets recycled into an
+image component.
+
+**Incorrect (single component with conditionals):**
+
+```tsx
+type Item = { id: string; text?: string; imageUrl?: string; isHeader?: boolean }
+
+function ListItem({ item }: { item: Item }) {
+  if (item.isHeader) {
+    return <HeaderItem title={item.text} />
+  }
+  if (item.imageUrl) {
+    return <ImageItem url={item.imageUrl} />
+  }
+  return <MessageItem text={item.text} />
+}
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      renderItem={({ item }) => <ListItem item={item} />}
+      recycleItems
+    />
+  )
+}
+```
+
+**Correct (typed items with separate components):**
+
+```tsx
+type HeaderItem = { id: string; type: 'header'; title: string }
+type MessageItem = { id: string; type: 'message'; text: string }
+type ImageItem = { id: string; type: 'image'; url: string }
+type FeedItem = HeaderItem | MessageItem | ImageItem
+
+function Feed({ items }: { items: FeedItem[] }) {
+  return (
+    <LegendList
+      data={items}
+      keyExtractor={(item) => item.id}
+      getItemType={(item) => item.type}
+      renderItem={({ item }) => {
+        switch (item.type) {
+          case 'header':
+            return <SectionHeader title={item.title} />
+          case 'message':
+            return <MessageRow text={item.text} />
+          case 'image':
+            return <ImageRow url={item.url} />
+        }
+      }}
+      recycleItems
+    />
+  )
+}
+```
+
+**Why this matters:**
+
+- **Recycling efficiency**: Items with the same type share a recycling pool
+- **No layout thrashing**: A header never recycles into an image cell
+- **Type safety**: TypeScript can narrow the item type in each branch
+- **Better size estimation**: Use `getEstimatedItemSize` with `itemType` for
+  accurate estimates per type
+
+```tsx
+<LegendList
+  data={items}
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type}
+  getEstimatedItemSize={(index, item, itemType) => {
+    switch (itemType) {
+      case 'header':
+        return 48
+      case 'message':
+        return 72
+      case 'image':
+        return 300
+      default:
+        return 72
+    }
+  }}
+  renderItem={({ item }) => {
+    /* ... */
+  }}
+  recycleItems
+/>
+```
+
+Reference:
+[LegendList getItemType](https://legendapp.com/open-source/list/api/props/#getitemtype-v2)
diff --git a/skills/vercel-react-native-skills/rules/list-performance-virtualize.md b/skills/vercel-react-native-skills/rules/list-performance-virtualize.md
new file mode 100644
index 00000000..8a393ba1
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/list-performance-virtualize.md
@@ -0,0 +1,67 @@
+---
+title: Use a List Virtualizer for Any List
+impact: HIGH
+impactDescription: reduced memory, faster mounts
+tags: lists, performance, virtualization, scrollview
+---
+
+## Use a List Virtualizer for Any List
+
+Use a list virtualizer like LegendList or FlashList instead of ScrollView with
+mapped children—even for short lists. Virtualizers only render visible items,
+reducing memory usage and mount time. ScrollView renders all children upfront,
+which gets expensive quickly.
+
+**Incorrect (ScrollView renders all items at once):**
+
+```tsx
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <ScrollView>
+      {items.map((item) => (
+        <ItemCard key={item.id} item={item} />
+      ))}
+    </ScrollView>
+  )
+}
+// 50 items = 50 components mounted, even if only 10 visible
+```
+
+**Correct (virtualizer renders only visible items):**
+
+```tsx
+import { LegendList } from '@legendapp/list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <LegendList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+      estimatedItemSize={80}
+    />
+  )
+}
+// Only ~10-15 visible items mounted at a time
+```
+
+**Alternative (FlashList):**
+
+```tsx
+import { FlashList } from '@shopify/flash-list'
+
+function Feed({ items }: { items: Item[] }) {
+  return (
+    <FlashList
+      data={items}
+      // if you aren't using React Compiler, wrap these with useCallback
+      renderItem={({ item }) => <ItemCard item={item} />}
+      keyExtractor={(item) => item.id}
+    />
+  )
+}
+```
+
+Benefits apply to any screen with scrollable content—profiles, settings, feeds,
+search results. Default to virtualization.
diff --git a/skills/vercel-react-native-skills/rules/monorepo-native-deps-in-app.md b/skills/vercel-react-native-skills/rules/monorepo-native-deps-in-app.md
new file mode 100644
index 00000000..ff85d767
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/monorepo-native-deps-in-app.md
@@ -0,0 +1,46 @@
+---
+title: Install Native Dependencies in App Directory
+impact: CRITICAL
+impactDescription: required for autolinking to work
+tags: monorepo, native, autolinking, installation
+---
+
+## Install Native Dependencies in App Directory
+
+In a monorepo, packages with native code must be installed in the native app's
+directory directly. Autolinking only scans the app's `node_modules`—it won't
+find native dependencies installed in other packages.
+
+**Incorrect (native dep in shared package only):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # missing react-native-reanimated
+```
+
+Autolinking fails—native code not linked.
+
+**Correct (native dep in app directory):**
+
+```
+packages/
+  ui/
+    package.json  # has react-native-reanimated
+  app/
+    package.json  # also has react-native-reanimated
+```
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Even if the shared package uses the native dependency, the app must also list it
+for autolinking to detect and link the native code.
diff --git a/skills/vercel-react-native-skills/rules/monorepo-single-dependency-versions.md b/skills/vercel-react-native-skills/rules/monorepo-single-dependency-versions.md
new file mode 100644
index 00000000..1087dfa5
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/monorepo-single-dependency-versions.md
@@ -0,0 +1,63 @@
+---
+title: Use Single Dependency Versions Across Monorepo
+impact: MEDIUM
+impactDescription: avoids duplicate bundles, version conflicts
+tags: monorepo, dependencies, installation
+---
+
+## Use Single Dependency Versions Across Monorepo
+
+Use a single version of each dependency across all packages in your monorepo.
+Prefer exact versions over ranges. Multiple versions cause duplicate code in
+bundles, runtime conflicts, and inconsistent behavior across packages.
+
+Use a tool like syncpack to enforce this. As a last resort, use yarn resolutions
+or npm overrides.
+
+**Incorrect (version ranges, multiple versions):**
+
+```json
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.0.0"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "^3.5.0"
+  }
+}
+```
+
+**Correct (exact versions, single source of truth):**
+
+```json
+// package.json (root)
+{
+  "pnpm": {
+    "overrides": {
+      "react-native-reanimated": "3.16.1"
+    }
+  }
+}
+
+// packages/app/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+
+// packages/ui/package.json
+{
+  "dependencies": {
+    "react-native-reanimated": "3.16.1"
+  }
+}
+```
+
+Use your package manager's override/resolution feature to enforce versions at
+the root. When adding dependencies, specify exact versions without `^` or `~`.
diff --git a/skills/vercel-react-native-skills/rules/navigation-native-navigators.md b/skills/vercel-react-native-skills/rules/navigation-native-navigators.md
new file mode 100644
index 00000000..035c5fd3
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/navigation-native-navigators.md
@@ -0,0 +1,188 @@
+---
+title: Use Native Navigators for Navigation
+impact: HIGH
+impactDescription: native performance, platform-appropriate UI
+tags: navigation, react-navigation, expo-router, native-stack, tabs
+---
+
+## Use Native Navigators for Navigation
+
+Always use native navigators instead of JS-based ones. Native navigators use
+platform APIs (UINavigationController on iOS, Fragment on Android) for better
+performance and native behavior.
+
+**For stacks:** Use `@react-navigation/native-stack` or expo-router's default
+stack (which uses native-stack). Avoid `@react-navigation/stack`.
+
+**For tabs:** Use `react-native-bottom-tabs` (native) or expo-router's native
+tabs. Avoid `@react-navigation/bottom-tabs` when native feel matters.
+
+### Stack Navigation
+
+**Incorrect (JS stack navigator):**
+
+```tsx
+import { createStackNavigator } from '@react-navigation/stack'
+
+const Stack = createStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (native stack with react-navigation):**
+
+```tsx
+import { createNativeStackNavigator } from '@react-navigation/native-stack'
+
+const Stack = createNativeStackNavigator()
+
+function App() {
+  return (
+    <Stack.Navigator>
+      <Stack.Screen name='Home' component={HomeScreen} />
+      <Stack.Screen name='Details' component={DetailsScreen} />
+    </Stack.Navigator>
+  )
+}
+```
+
+**Correct (expo-router uses native stack by default):**
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router'
+
+export default function Layout() {
+  return <Stack />
+}
+```
+
+### Tab Navigation
+
+**Incorrect (JS bottom tabs):**
+
+```tsx
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs'
+
+const Tab = createBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen name='Home' component={HomeScreen} />
+      <Tab.Screen name='Settings' component={SettingsScreen} />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (native bottom tabs with react-navigation):**
+
+```tsx
+import { createNativeBottomTabNavigator } from '@bottom-tabs/react-navigation'
+
+const Tab = createNativeBottomTabNavigator()
+
+function App() {
+  return (
+    <Tab.Navigator>
+      <Tab.Screen
+        name='Home'
+        component={HomeScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'house' }),
+        }}
+      />
+      <Tab.Screen
+        name='Settings'
+        component={SettingsScreen}
+        options={{
+          tabBarIcon: () => ({ sfSymbol: 'gear' }),
+        }}
+      />
+    </Tab.Navigator>
+  )
+}
+```
+
+**Correct (expo-router native tabs):**
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { NativeTabs } from 'expo-router/unstable-native-tabs'
+
+export default function TabLayout() {
+  return (
+    <NativeTabs>
+      <NativeTabs.Trigger name='index'>
+        <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='house.fill' md='home' />
+      </NativeTabs.Trigger>
+      <NativeTabs.Trigger name='settings'>
+        <NativeTabs.Trigger.Label>Settings</NativeTabs.Trigger.Label>
+        <NativeTabs.Trigger.Icon sf='gear' md='settings' />
+      </NativeTabs.Trigger>
+    </NativeTabs>
+  )
+}
+```
+
+On iOS, native tabs automatically enable `contentInsetAdjustmentBehavior` on the
+first `ScrollView` at the root of each tab screen, so content scrolls correctly
+behind the translucent tab bar. If you need to disable this, use
+`disableAutomaticContentInsets` on the trigger.
+
+### Prefer Native Header Options Over Custom Components
+
+**Incorrect (custom header component):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    header: () => <CustomHeader title='Profile' />,
+  }}
+/>
+```
+
+**Correct (native header options):**
+
+```tsx
+<Stack.Screen
+  name='Profile'
+  component={ProfileScreen}
+  options={{
+    title: 'Profile',
+    headerLargeTitleEnabled: true,
+    headerSearchBarOptions: {
+      placeholder: 'Search',
+    },
+  }}
+/>
+```
+
+Native headers support iOS large titles, search bars, blur effects, and proper
+safe area handling automatically.
+
+### Why Native Navigators
+
+- **Performance**: Native transitions and gestures run on the UI thread
+- **Platform behavior**: Automatic iOS large titles, Android material design
+- **System integration**: Scroll-to-top on tab tap, PiP avoidance, proper safe
+  areas
+- **Accessibility**: Platform accessibility features work automatically
+
+Reference:
+
+- [React Navigation Native Stack](https://reactnavigation.org/docs/native-stack-navigator)
+- [React Native Bottom Tabs with React Navigation](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-react-navigation)
+- [React Native Bottom Tabs with Expo Router](https://oss.callstack.com/react-native-bottom-tabs/docs/guides/usage-with-expo-router)
+- [Expo Router Native Tabs](https://docs.expo.dev/router/advanced/native-tabs)
diff --git a/skills/vercel-react-native-skills/rules/react-compiler-destructure-functions.md b/skills/vercel-react-native-skills/rules/react-compiler-destructure-functions.md
new file mode 100644
index 00000000..f76c25ac
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-compiler-destructure-functions.md
@@ -0,0 +1,50 @@
+---
+title: Destructure Functions Early in Render (React Compiler)
+impact: HIGH
+impactDescription: stable references, fewer re-renders
+tags: rerender, hooks, performance, react-compiler
+---
+
+## Destructure Functions Early in Render
+
+This rule is only applicable if you are using the React Compiler.
+
+Destructure functions from hooks at the top of render scope. Never dot into
+objects to call functions. Destructured functions are stable references; dotting
+creates new references and breaks memoization.
+
+**Incorrect (dotting into object):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton(props) {
+  const router = useRouter()
+
+  // bad: react-compiler will key the cache on "props" and "router", which are objects that change each render
+  const handlePress = () => {
+    props.onSave()
+    router.push('/success') // unstable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
+
+**Correct (destructure early):**
+
+```tsx
+import { useRouter } from 'expo-router'
+
+function SaveButton({ onSave }) {
+  const { push } = useRouter()
+
+  // good: react-compiler will key on push and onSave
+  const handlePress = () => {
+    onSave()
+    push('/success') // stable reference
+  }
+
+  return <Button onPress={handlePress}>Save</Button>
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/react-compiler-reanimated-shared-values.md b/skills/vercel-react-native-skills/rules/react-compiler-reanimated-shared-values.md
new file mode 100644
index 00000000..0dcbaf47
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-compiler-reanimated-shared-values.md
@@ -0,0 +1,48 @@
+---
+title: Use .get() and .set() for Reanimated Shared Values (not .value)
+impact: LOW
+impactDescription: required for React Compiler compatibility
+tags: reanimated, react-compiler, shared-values
+---
+
+## Use .get() and .set() for Shared Values with React Compiler
+
+With React Compiler enabled, use `.get()` and `.set()` instead of reading or
+writing `.value` directly on Reanimated shared values. The compiler can't track
+property access—explicit methods ensure correct behavior.
+
+**Incorrect (breaks with React Compiler):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.value = count.value + 1 // opts out of react compiler
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.value}`} />
+}
+```
+
+**Correct (React Compiler compatible):**
+
+```tsx
+import { useSharedValue } from 'react-native-reanimated'
+
+function Counter() {
+  const count = useSharedValue(0)
+
+  const increment = () => {
+    count.set(count.get() + 1)
+  }
+
+  return <Button onPress={increment} title={`Count: ${count.get()}`} />
+}
+```
+
+See the
+[Reanimated docs](https://docs.swmansion.com/react-native-reanimated/docs/core/useSharedValue/#react-compiler-support)
+for more.
diff --git a/skills/vercel-react-native-skills/rules/react-state-dispatcher.md b/skills/vercel-react-native-skills/rules/react-state-dispatcher.md
new file mode 100644
index 00000000..93e8b6db
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-state-dispatcher.md
@@ -0,0 +1,91 @@
+---
+title: useState Dispatch updaters for State That Depends on Current Value
+impact: MEDIUM
+impactDescription: avoids stale closures, prevents unnecessary re-renders
+tags: state, hooks, useState, callbacks
+---
+
+## Use Dispatch Updaters for State That Depends on Current Value
+
+When the next state depends on the current state, use a dispatch updater
+(`setState(prev => ...)`) instead of reading the state variable directly in a
+callback. This avoids stale closures and ensures you're comparing against the
+latest value.
+
+**Incorrect (reads state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  // size may be stale in this closure
+  if (size?.width !== width || size?.height !== height) {
+    setSize({ width, height })
+  }
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => {
+    if (prev?.width === width && prev?.height === height) return prev
+    return { width, height }
+  })
+}
+```
+
+Returning the previous value from the updater skips the re-render.
+
+For primitive states, you don't need to compare values before firing a
+re-render.
+
+**Incorrect (unnecessary comparison for primitive state):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize((prev) => (prev === width ? prev : width))
+}
+```
+
+**Correct (sets primitive state directly):**
+
+```tsx
+const [size, setSize] = useState<Size | undefined>(undefined)
+
+const onLayout = (e: LayoutChangeEvent) => {
+  const { width, height } = e.nativeEvent.layout
+  setSize(width)
+}
+```
+
+However, if the next state depends on the current state, you should still use a
+dispatch updater.
+
+**Incorrect (reads state directly from the callback):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount(count + 1)
+}
+```
+
+**Correct (dispatch updater):**
+
+```tsx
+const [count, setCount] = useState(0)
+
+const onTap = () => {
+  setCount((prev) => prev + 1)
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/react-state-fallback.md b/skills/vercel-react-native-skills/rules/react-state-fallback.md
new file mode 100644
index 00000000..204f3466
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-state-fallback.md
@@ -0,0 +1,56 @@
+---
+title: Use fallback state instead of initialState
+impact: MEDIUM
+impactDescription: reactive fallbacks without syncing
+tags: state, hooks, derived-state, props, initialState
+---
+
+## Use fallback state instead of initialState
+
+Use `undefined` as initial state and nullish coalescing (`??`) to fall back to
+parent or server values. State represents user intent only—`undefined` means
+"user hasn't chosen yet." This enables reactive fallbacks that update when the
+source changes, not just on initial render.
+
+**Incorrect (syncs state, loses reactivity):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [enabled, setEnabled] = useState(defaultEnabled)
+  // If fallbackEnabled changes, state is stale
+  // State mixes user intent with default value
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**Correct (state is user intent, reactive fallback):**
+
+```tsx
+type Props = { fallbackEnabled: boolean }
+
+function Toggle({ fallbackEnabled }: Props) {
+  const [_enabled, setEnabled] = useState<boolean | undefined>(undefined)
+  const enabled = _enabled ?? defaultEnabled
+  // undefined = user hasn't touched it, falls back to prop
+  // If defaultEnabled changes, component reflects it
+  // Once user interacts, their choice persists
+
+  return <Switch value={enabled} onValueChange={setEnabled} />
+}
+```
+
+**With server data:**
+
+```tsx
+function ProfileForm({ data }: { data: User }) {
+  const [_theme, setTheme] = useState<string | undefined>(undefined)
+  const theme = _theme ?? data.theme
+  // Shows server value until user overrides
+  // Server refetch updates the fallback automatically
+
+  return <ThemePicker value={theme} onChange={setTheme} />
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/react-state-minimize.md b/skills/vercel-react-native-skills/rules/react-state-minimize.md
new file mode 100644
index 00000000..64605b6c
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/react-state-minimize.md
@@ -0,0 +1,65 @@
+---
+title: Minimize State Variables and Derive Values
+impact: MEDIUM
+impactDescription: fewer re-renders, less state drift
+tags: state, derived-state, hooks, optimization
+---
+
+## Minimize State Variables and Derive Values
+
+Use the fewest state variables possible. If a value can be computed from existing state or props, derive it during render instead of storing it in state. Redundant state causes unnecessary re-renders and can drift out of sync.
+
+**Incorrect (redundant state):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const [total, setTotal] = useState(0)
+  const [itemCount, setItemCount] = useState(0)
+
+  useEffect(() => {
+    setTotal(items.reduce((sum, item) => sum + item.price, 0))
+    setItemCount(items.length)
+  }, [items])
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Correct (derived values):**
+
+```tsx
+function Cart({ items }: { items: Item[] }) {
+  const total = items.reduce((sum, item) => sum + item.price, 0)
+  const itemCount = items.length
+
+  return (
+    <View>
+      <Text>{itemCount} items</Text>
+      <Text>Total: ${total}</Text>
+    </View>
+  )
+}
+```
+
+**Another example:**
+
+```tsx
+// Incorrect: storing both firstName, lastName, AND fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const [fullName, setFullName] = useState('')
+
+// Correct: derive fullName
+const [firstName, setFirstName] = useState('')
+const [lastName, setLastName] = useState('')
+const fullName = `${firstName} ${lastName}`
+```
+
+State should be the minimal source of truth. Everything else is derived.
+
+Reference: [Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)
diff --git a/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md b/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md
new file mode 100644
index 00000000..30f05d3f
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/rendering-no-falsy-and.md
@@ -0,0 +1,74 @@
+---
+title: Never Use && with Potentially Falsy Values
+impact: CRITICAL
+impactDescription: prevents production crash
+tags: rendering, conditional, jsx, crash
+---
+
+## Never Use && with Potentially Falsy Values
+
+Never use `{value && <Component />}` when `value` could be an empty string or
+`0`. These are falsy but JSX-renderable—React Native will try to render them as
+text outside a `<Text>` component, causing a hard crash in production.
+
+**Incorrect (crashes if count is 0 or name is ""):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name && <Text>{name}</Text>}
+      {count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+// If name="" or count=0, renders the falsy value → crash
+```
+
+**Correct (ternary with null):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {name ? <Text>{name}</Text> : null}
+      {count ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+**Correct (explicit boolean coercion):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  return (
+    <View>
+      {!!name && <Text>{name}</Text>}
+      {!!count && <Text>{count} items</Text>}
+    </View>
+  )
+}
+```
+
+**Best (early return):**
+
+```tsx
+function Profile({ name, count }: { name: string; count: number }) {
+  if (!name) return null
+
+  return (
+    <View>
+      <Text>{name}</Text>
+      {count > 0 ? <Text>{count} items</Text> : null}
+    </View>
+  )
+}
+```
+
+Early returns are clearest. When using conditionals inline, prefer ternary or
+explicit boolean checks.
+
+**Lint rule:** Enable `react/jsx-no-leaked-render` from
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react/blob/master/docs/rules/jsx-no-leaked-render.md)
+to catch this automatically.
diff --git a/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md b/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md
new file mode 100644
index 00000000..fd1b9f40
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/rendering-text-in-text-component.md
@@ -0,0 +1,36 @@
+---
+title: Wrap Strings in Text Components
+impact: CRITICAL
+impactDescription: prevents runtime crash
+tags: rendering, text, core
+---
+
+## Wrap Strings in Text Components
+
+Strings must be rendered inside `<Text>`. React Native crashes if a string is a
+direct child of `<View>`.
+
+**Incorrect (crashes):**
+
+```tsx
+import { View } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return <View>Hello, {name}!</View>
+}
+// Error: Text strings must be rendered within a <Text> component.
+```
+
+**Correct:**
+
+```tsx
+import { View, Text } from 'react-native'
+
+function Greeting({ name }: { name: string }) {
+  return (
+    <View>
+      <Text>Hello, {name}!</Text>
+    </View>
+  )
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/scroll-position-no-state.md b/skills/vercel-react-native-skills/rules/scroll-position-no-state.md
new file mode 100644
index 00000000..a5760cd2
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/scroll-position-no-state.md
@@ -0,0 +1,82 @@
+---
+title: Never Track Scroll Position in useState
+impact: HIGH
+impactDescription: prevents render thrashing during scroll
+tags: scroll, performance, reanimated, useRef
+---
+
+## Never Track Scroll Position in useState
+
+Never store scroll position in `useState`. Scroll events fire rapidly—state
+updates cause render thrashing and dropped frames. Use a Reanimated shared value
+for animations or a ref for non-reactive tracking.
+
+**Incorrect (useState causes jank):**
+
+```tsx
+import { useState } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const [scrollY, setScrollY] = useState(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    setScrollY(e.nativeEvent.contentOffset.y) // re-renders on every frame
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
+
+**Correct (Reanimated for animations):**
+
+```tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedScrollHandler,
+} from 'react-native-reanimated'
+
+function Feed() {
+  const scrollY = useSharedValue(0)
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollY.value = e.contentOffset.y // runs on UI thread, no re-render
+    },
+  })
+
+  return (
+    <Animated.ScrollView
+      onScroll={onScroll}
+      // higher number has better performance, but it fires less often.
+      // unset this if you need higher precision over performance.
+      scrollEventThrottle={16}
+    />
+  )
+}
+```
+
+**Correct (ref for non-reactive tracking):**
+
+```tsx
+import { useRef } from 'react'
+import {
+  ScrollView,
+  NativeSyntheticEvent,
+  NativeScrollEvent,
+} from 'react-native'
+
+function Feed() {
+  const scrollY = useRef(0)
+
+  const onScroll = (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+    scrollY.current = e.nativeEvent.contentOffset.y // no re-render
+  }
+
+  return <ScrollView onScroll={onScroll} scrollEventThrottle={16} />
+}
+```
diff --git a/skills/vercel-react-native-skills/rules/state-ground-truth.md b/skills/vercel-react-native-skills/rules/state-ground-truth.md
new file mode 100644
index 00000000..c3c4bd9e
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/state-ground-truth.md
@@ -0,0 +1,80 @@
+---
+title: State Must Represent Ground Truth
+impact: HIGH
+impactDescription: cleaner logic, easier debugging, single source of truth
+tags: state, derived-state, reanimated, hooks
+---
+
+## State Must Represent Ground Truth
+
+State variables—both React `useState` and Reanimated shared values—should
+represent the actual state of something (e.g., `pressed`, `progress`, `isOpen`),
+not derived visual values (e.g., `scale`, `opacity`, `translateY`). Derive
+visual values from state using computation or interpolation.
+
+**Incorrect (storing the visual output):**
+
+```tsx
+const scale = useSharedValue(1)
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    scale.set(withTiming(0.95))
+  })
+  .onFinalize(() => {
+    scale.set(withTiming(1))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.get() }],
+}))
+```
+
+**Correct (storing the state, deriving the visual):**
+
+```tsx
+const pressed = useSharedValue(0) // 0 = not pressed, 1 = pressed
+
+const tap = Gesture.Tap()
+  .onBegin(() => {
+    pressed.set(withTiming(1))
+  })
+  .onFinalize(() => {
+    pressed.set(withTiming(0))
+  })
+
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: interpolate(pressed.get(), [0, 1], [1, 0.95]) }],
+}))
+```
+
+**Why this matters:**
+
+State variables should represent real "state", not necessarily a desired end
+result.
+
+1. **Single source of truth** — The state (`pressed`) describes what's
+   happening; visuals are derived
+2. **Easier to extend** — Adding opacity, rotation, or other effects just
+   requires more interpolations from the same state
+3. **Debugging** — Inspecting `pressed = 1` is clearer than `scale = 0.95`
+4. **Reusable logic** — The same `pressed` value can drive multiple visual
+   properties
+
+**Same principle for React state:**
+
+```tsx
+// Incorrect: storing derived values
+const [isExpanded, setIsExpanded] = useState(false)
+const [height, setHeight] = useState(0)
+
+useEffect(() => {
+  setHeight(isExpanded ? 200 : 0)
+}, [isExpanded])
+
+// Correct: derive from state
+const [isExpanded, setIsExpanded] = useState(false)
+const height = isExpanded ? 200 : 0
+```
+
+State is the minimal truth. Everything else is derived.
diff --git a/skills/vercel-react-native-skills/rules/ui-expo-image.md b/skills/vercel-react-native-skills/rules/ui-expo-image.md
new file mode 100644
index 00000000..72d768f1
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-expo-image.md
@@ -0,0 +1,66 @@
+---
+title: Use expo-image for Optimized Images
+impact: HIGH
+impactDescription: memory efficiency, caching, blurhash placeholders, progressive loading
+tags: images, performance, expo-image, ui
+---
+
+## Use expo-image for Optimized Images
+
+Use `expo-image` instead of React Native's `Image`. It provides memory-efficient caching, blurhash placeholders, progressive loading, and better performance for lists.
+
+**Incorrect (React Native Image):**
+
+```tsx
+import { Image } from 'react-native'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**Correct (expo-image):**
+
+```tsx
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return <Image source={{ uri: url }} style={styles.avatar} />
+}
+```
+
+**With blurhash placeholder:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  placeholder={{ blurhash: 'LGF5]+Yk^6#M@-5c,1J5@[or[Q6.' }}
+  contentFit="cover"
+  transition={200}
+  style={styles.image}
+/>
+```
+
+**With priority and caching:**
+
+```tsx
+<Image
+  source={{ uri: url }}
+  priority="high"
+  cachePolicy="memory-disk"
+  style={styles.hero}
+/>
+```
+
+**Key props:**
+
+- `placeholder` — Blurhash or thumbnail while loading
+- `contentFit` — `cover`, `contain`, `fill`, `scale-down`
+- `transition` — Fade-in duration (ms)
+- `priority` — `low`, `normal`, `high`
+- `cachePolicy` — `memory`, `disk`, `memory-disk`, `none`
+- `recyclingKey` — Unique key for list recycling
+
+For cross-platform (web + native), use `SolitoImage` from `solito/image` which uses `expo-image` under the hood.
+
+Reference: [expo-image](https://docs.expo.dev/versions/latest/sdk/image/)
diff --git a/skills/vercel-react-native-skills/rules/ui-image-gallery.md b/skills/vercel-react-native-skills/rules/ui-image-gallery.md
new file mode 100644
index 00000000..ef26d962
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-image-gallery.md
@@ -0,0 +1,104 @@
+---
+title: Use Galeria for Image Galleries and Lightbox
+impact: MEDIUM
+impactDescription:
+  native shared element transitions, pinch-to-zoom, pan-to-close
+tags: images, gallery, lightbox, expo-image, ui
+---
+
+## Use Galeria for Image Galleries and Lightbox
+
+For image galleries with lightbox (tap to fullscreen), use `@nandorojo/galeria`.
+It provides native shared element transitions with pinch-to-zoom, double-tap
+zoom, and pan-to-close. Works with any image component including `expo-image`.
+
+**Incorrect (custom modal implementation):**
+
+```tsx
+function ImageGallery({ urls }: { urls: string[] }) {
+  const [selected, setSelected] = useState<string | null>(null)
+
+  return (
+    <>
+      {urls.map((url) => (
+        <Pressable key={url} onPress={() => setSelected(url)}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Pressable>
+      ))}
+      <Modal visible={!!selected} onRequestClose={() => setSelected(null)}>
+        <Image source={{ uri: selected! }} style={styles.fullscreen} />
+      </Modal>
+    </>
+  )
+}
+```
+
+**Correct (Galeria with expo-image):**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function ImageGallery({ urls }: { urls: string[] }) {
+  return (
+    <Galeria urls={urls}>
+      {urls.map((url, index) => (
+        <Galeria.Image index={index} key={url}>
+          <Image source={{ uri: url }} style={styles.thumbnail} />
+        </Galeria.Image>
+      ))}
+    </Galeria>
+  )
+}
+```
+
+**Single image:**
+
+```tsx
+import { Galeria } from '@nandorojo/galeria'
+import { Image } from 'expo-image'
+
+function Avatar({ url }: { url: string }) {
+  return (
+    <Galeria urls={[url]}>
+      <Galeria.Image>
+        <Image source={{ uri: url }} style={styles.avatar} />
+      </Galeria.Image>
+    </Galeria>
+  )
+}
+```
+
+**With low-res thumbnails and high-res fullscreen:**
+
+```tsx
+<Galeria urls={highResUrls}>
+  {lowResUrls.map((url, index) => (
+    <Galeria.Image index={index} key={url}>
+      <Image source={{ uri: url }} style={styles.thumbnail} />
+    </Galeria.Image>
+  ))}
+</Galeria>
+```
+
+**With FlashList:**
+
+```tsx
+<Galeria urls={urls}>
+  <FlashList
+    data={urls}
+    renderItem={({ item, index }) => (
+      <Galeria.Image index={index}>
+        <Image source={{ uri: item }} style={styles.thumbnail} />
+      </Galeria.Image>
+    )}
+    numColumns={3}
+    estimatedItemSize={100}
+  />
+</Galeria>
+```
+
+Works with `expo-image`, `SolitoImage`, `react-native` Image, or any image
+component.
+
+Reference: [Galeria](https://github.com/nandorojo/galeria)
diff --git a/skills/vercel-react-native-skills/rules/ui-measure-views.md b/skills/vercel-react-native-skills/rules/ui-measure-views.md
new file mode 100644
index 00000000..8b783fee
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-measure-views.md
@@ -0,0 +1,78 @@
+---
+title: Measuring View Dimensions
+impact: MEDIUM
+impactDescription: synchronous measurement, avoid unnecessary re-renders
+tags: layout, measurement, onLayout, useLayoutEffect
+---
+
+## Measuring View Dimensions
+
+Use both `useLayoutEffect` (synchronous) and `onLayout` (for updates). The sync
+measurement gives you the initial size immediately; `onLayout` keeps it current
+when the view changes. For non-primitive states, use a dispatch updater to
+compare values and avoid unnecessary re-renders.
+
+**Height only:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [height, setHeight] = useState<number | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    // Sync measurement on mount (RN 0.82+)
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setHeight(rect.height)
+    // Pre-0.82: ref.current?.measure((x, y, w, h) => setHeight(h))
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    setHeight(e.nativeEvent.layout.height)
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+**Both dimensions:**
+
+```tsx
+import { useLayoutEffect, useRef, useState } from 'react'
+import { View, LayoutChangeEvent } from 'react-native'
+
+type Size = { width: number; height: number }
+
+function MeasuredBox({ children }: { children: React.ReactNode }) {
+  const ref = useRef<View>(null)
+  const [size, setSize] = useState<Size | undefined>(undefined)
+
+  useLayoutEffect(() => {
+    const rect = ref.current?.getBoundingClientRect()
+    if (rect) setSize({ width: rect.width, height: rect.height })
+  }, [])
+
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout
+    setSize((prev) => {
+      // for non-primitive states, compare values before firing a re-render
+      if (prev?.width === width && prev?.height === height) return prev
+      return { width, height }
+    })
+  }
+
+  return (
+    <View ref={ref} onLayout={onLayout}>
+      {children}
+    </View>
+  )
+}
+```
+
+Use functional setState to compare—don't read state directly in the callback.
diff --git a/skills/vercel-react-native-skills/rules/ui-menus.md b/skills/vercel-react-native-skills/rules/ui-menus.md
new file mode 100644
index 00000000..5168bc20
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-menus.md
@@ -0,0 +1,174 @@
+---
+title: Use Native Menus for Dropdowns and Context Menus
+impact: HIGH
+impactDescription: native accessibility, platform-consistent UX
+tags: user-interface, menus, context-menus, zeego, accessibility
+---
+
+## Use Native Menus for Dropdowns and Context Menus
+
+Use native platform menus instead of custom JS implementations. Native menus
+provide built-in accessibility, consistent platform UX, and better performance.
+Use [zeego](https://zeego.dev) for cross-platform native menus.
+
+**Incorrect (custom JS menu):**
+
+```tsx
+import { useState } from 'react'
+import { View, Pressable, Text } from 'react-native'
+
+function MyMenu() {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <View>
+      <Pressable onPress={() => setOpen(!open)}>
+        <Text>Open Menu</Text>
+      </Pressable>
+      {open && (
+        <View style={{ position: 'absolute', top: 40 }}>
+          <Pressable onPress={() => console.log('edit')}>
+            <Text>Edit</Text>
+          </Pressable>
+          <Pressable onPress={() => console.log('delete')}>
+            <Text>Delete</Text>
+          </Pressable>
+        </View>
+      )}
+    </View>
+  )
+}
+```
+
+**Correct (native menu with zeego):**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MyMenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Open Menu</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='edit' onSelect={() => console.log('edit')}>
+          <DropdownMenu.ItemTitle>Edit</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Item
+          key='delete'
+          destructive
+          onSelect={() => console.log('delete')}
+        >
+          <DropdownMenu.ItemTitle>Delete</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Context menu (long-press):**
+
+```tsx
+import * as ContextMenu from 'zeego/context-menu'
+
+function MyContextMenu() {
+  return (
+    <ContextMenu.Root>
+      <ContextMenu.Trigger>
+        <View style={{ padding: 20 }}>
+          <Text>Long press me</Text>
+        </View>
+      </ContextMenu.Trigger>
+
+      <ContextMenu.Content>
+        <ContextMenu.Item key='copy' onSelect={() => console.log('copy')}>
+          <ContextMenu.ItemTitle>Copy</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+
+        <ContextMenu.Item key='paste' onSelect={() => console.log('paste')}>
+          <ContextMenu.ItemTitle>Paste</ContextMenu.ItemTitle>
+        </ContextMenu.Item>
+      </ContextMenu.Content>
+    </ContextMenu.Root>
+  )
+}
+```
+
+**Checkbox items:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function SettingsMenu() {
+  const [notifications, setNotifications] = useState(true)
+
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Settings</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.CheckboxItem
+          key='notifications'
+          value={notifications}
+          onValueChange={() => setNotifications((prev) => !prev)}
+        >
+          <DropdownMenu.ItemIndicator />
+          <DropdownMenu.ItemTitle>Notifications</DropdownMenu.ItemTitle>
+        </DropdownMenu.CheckboxItem>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+**Submenus:**
+
+```tsx
+import * as DropdownMenu from 'zeego/dropdown-menu'
+
+function MenuWithSubmenu() {
+  return (
+    <DropdownMenu.Root>
+      <DropdownMenu.Trigger>
+        <Pressable>
+          <Text>Options</Text>
+        </Pressable>
+      </DropdownMenu.Trigger>
+
+      <DropdownMenu.Content>
+        <DropdownMenu.Item key='home' onSelect={() => console.log('home')}>
+          <DropdownMenu.ItemTitle>Home</DropdownMenu.ItemTitle>
+        </DropdownMenu.Item>
+
+        <DropdownMenu.Sub>
+          <DropdownMenu.SubTrigger key='more'>
+            <DropdownMenu.ItemTitle>More Options</DropdownMenu.ItemTitle>
+          </DropdownMenu.SubTrigger>
+
+          <DropdownMenu.SubContent>
+            <DropdownMenu.Item key='settings'>
+              <DropdownMenu.ItemTitle>Settings</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+
+            <DropdownMenu.Item key='help'>
+              <DropdownMenu.ItemTitle>Help</DropdownMenu.ItemTitle>
+            </DropdownMenu.Item>
+          </DropdownMenu.SubContent>
+        </DropdownMenu.Sub>
+      </DropdownMenu.Content>
+    </DropdownMenu.Root>
+  )
+}
+```
+
+Reference: [Zeego Documentation](https://zeego.dev/components/dropdown-menu)
diff --git a/skills/vercel-react-native-skills/rules/ui-native-modals.md b/skills/vercel-react-native-skills/rules/ui-native-modals.md
new file mode 100644
index 00000000..f560e11e
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-native-modals.md
@@ -0,0 +1,77 @@
+---
+title: Use Native Modals Over JS-Based Bottom Sheets
+impact: HIGH
+impactDescription: native performance, gestures, accessibility
+tags: modals, bottom-sheet, native, react-navigation
+---
+
+## Use Native Modals Over JS-Based Bottom Sheets
+
+Use native `<Modal>` with `presentationStyle="formSheet"` or React Navigation
+v7's native form sheet instead of JS-based bottom sheet libraries. Native modals
+have built-in gestures, accessibility, and better performance. Rely on native UI
+for low-level primitives.
+
+**Incorrect (JS-based bottom sheet):**
+
+```tsx
+import BottomSheet from 'custom-js-bottom-sheet'
+
+function MyScreen() {
+  const sheetRef = useRef<BottomSheet>(null)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => sheetRef.current?.expand()} title='Open' />
+      <BottomSheet ref={sheetRef} snapPoints={['50%', '90%']}>
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </BottomSheet>
+    </View>
+  )
+}
+```
+
+**Correct (native Modal with formSheet):**
+
+```tsx
+import { Modal, View, Text, Button } from 'react-native'
+
+function MyScreen() {
+  const [visible, setVisible] = useState(false)
+
+  return (
+    <View style={{ flex: 1 }}>
+      <Button onPress={() => setVisible(true)} title='Open' />
+      <Modal
+        visible={visible}
+        presentationStyle='formSheet'
+        animationType='slide'
+        onRequestClose={() => setVisible(false)}
+      >
+        <View>
+          <Text>Sheet content</Text>
+        </View>
+      </Modal>
+    </View>
+  )
+}
+```
+
+**Correct (React Navigation v7 native form sheet):**
+
+```tsx
+// In your navigator
+<Stack.Screen
+  name='Details'
+  component={DetailsScreen}
+  options={{
+    presentation: 'formSheet',
+    sheetAllowedDetents: 'fitToContents',
+  }}
+/>
+```
+
+Native modals provide swipe-to-dismiss, proper keyboard avoidance, and
+accessibility out of the box.
diff --git a/skills/vercel-react-native-skills/rules/ui-pressable.md b/skills/vercel-react-native-skills/rules/ui-pressable.md
new file mode 100644
index 00000000..31c3d204
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-pressable.md
@@ -0,0 +1,61 @@
+---
+title: Use Pressable Instead of Touchable Components
+impact: LOW
+impactDescription: modern API, more flexible
+tags: ui, pressable, touchable, gestures
+---
+
+## Use Pressable Instead of Touchable Components
+
+Never use `TouchableOpacity` or `TouchableHighlight`. Use `Pressable` from
+`react-native` or `react-native-gesture-handler` instead.
+
+**Incorrect (legacy Touchable components):**
+
+```tsx
+import { TouchableOpacity } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <TouchableOpacity onPress={onPress} activeOpacity={0.7}>
+      <Text>Press me</Text>
+    </TouchableOpacity>
+  )
+}
+```
+
+**Correct (Pressable):**
+
+```tsx
+import { Pressable } from 'react-native'
+
+function MyButton({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Press me</Text>
+    </Pressable>
+  )
+}
+```
+
+**Correct (Pressable from gesture handler for lists):**
+
+```tsx
+import { Pressable } from 'react-native-gesture-handler'
+
+function ListItem({ onPress }: { onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress}>
+      <Text>Item</Text>
+    </Pressable>
+  )
+}
+```
+
+Use `react-native-gesture-handler` Pressable inside scrollable lists for better
+gesture coordination, as long as you are using the ScrollView from
+`react-native-gesture-handler` as well.
+
+**For animated press states (scale, opacity changes):** Use `GestureDetector`
+with Reanimated shared values instead of Pressable's style callback. See the
+`animation-gesture-detector-press` rule.
diff --git a/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md b/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md
new file mode 100644
index 00000000..79812bc9
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-safe-area-scroll.md
@@ -0,0 +1,65 @@
+---
+title: Use contentInsetAdjustmentBehavior for Safe Areas
+impact: MEDIUM
+impactDescription: native safe area handling, no layout shifts
+tags: safe-area, scrollview, layout
+---
+
+## Use contentInsetAdjustmentBehavior for Safe Areas
+
+Use `contentInsetAdjustmentBehavior="automatic"` on the root ScrollView instead of wrapping content in SafeAreaView or manual padding. This lets iOS handle safe area insets natively with proper scroll behavior.
+
+**Incorrect (SafeAreaView wrapper):**
+
+```tsx
+import { SafeAreaView, ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <ScrollView>
+        <View>
+          <Text>Content</Text>
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+```
+
+**Incorrect (manual safe area padding):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+
+function MyScreen() {
+  const insets = useSafeAreaInsets()
+
+  return (
+    <ScrollView contentContainerStyle={{ paddingTop: insets.top }}>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+**Correct (native content inset adjustment):**
+
+```tsx
+import { ScrollView, View, Text } from 'react-native'
+
+function MyScreen() {
+  return (
+    <ScrollView contentInsetAdjustmentBehavior='automatic'>
+      <View>
+        <Text>Content</Text>
+      </View>
+    </ScrollView>
+  )
+}
+```
+
+The native approach handles dynamic safe areas (keyboard, toolbars) and allows content to scroll behind the status bar naturally.
diff --git a/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md b/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md
new file mode 100644
index 00000000..bbebc3b8
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-scrollview-content-inset.md
@@ -0,0 +1,45 @@
+---
+title: Use contentInset for Dynamic ScrollView Spacing
+impact: LOW
+impactDescription: smoother updates, no layout recalculation
+tags: scrollview, layout, contentInset, performance
+---
+
+## Use contentInset for Dynamic ScrollView Spacing
+
+When adding space to the top or bottom of a ScrollView that may change
+(keyboard, toolbars, dynamic content), use `contentInset` instead of padding.
+Changing `contentInset` doesn't trigger layout recalculation—it adjusts the
+scroll area without re-rendering content.
+
+**Incorrect (padding causes layout recalculation):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView contentContainerStyle={{ paddingBottom: bottomOffset }}>
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset triggers full layout recalculation
+```
+
+**Correct (contentInset for dynamic spacing):**
+
+```tsx
+function Feed({ bottomOffset }: { bottomOffset: number }) {
+  return (
+    <ScrollView
+      contentInset={{ bottom: bottomOffset }}
+      scrollIndicatorInsets={{ bottom: bottomOffset }}
+    >
+      {children}
+    </ScrollView>
+  )
+}
+// Changing bottomOffset only adjusts scroll bounds
+```
+
+Use `scrollIndicatorInsets` alongside `contentInset` to keep the scroll
+indicator aligned. For static spacing that never changes, padding is fine.
diff --git a/skills/vercel-react-native-skills/rules/ui-styling.md b/skills/vercel-react-native-skills/rules/ui-styling.md
new file mode 100644
index 00000000..3908de3c
--- /dev/null
+++ b/skills/vercel-react-native-skills/rules/ui-styling.md
@@ -0,0 +1,87 @@
+---
+title: Modern React Native Styling Patterns
+impact: MEDIUM
+impactDescription: consistent design, smoother borders, cleaner layouts
+tags: styling, css, layout, shadows, gradients
+---
+
+## Modern React Native Styling Patterns
+
+Follow these styling patterns for cleaner, more consistent React Native code.
+
+**Always use `borderCurve: 'continuous'` with `borderRadius`:**
+
+```tsx
+// Incorrect
+{ borderRadius: 12 }
+
+// Correct – smoother iOS-style corners
+{ borderRadius: 12, borderCurve: 'continuous' }
+```
+
+**Use `gap` instead of margin for spacing between elements:**
+
+```tsx
+// Incorrect – margin on children
+<View>
+  <Text style={{ marginBottom: 8 }}>Title</Text>
+  <Text style={{ marginBottom: 8 }}>Subtitle</Text>
+</View>
+
+// Correct – gap on parent
+<View style={{ gap: 8 }}>
+  <Text>Title</Text>
+  <Text>Subtitle</Text>
+</View>
+```
+
+**Use `padding` for space within, `gap` for space between:**
+
+```tsx
+<View style={{ padding: 16, gap: 12 }}>
+  <Text>First</Text>
+  <Text>Second</Text>
+</View>
+```
+
+**Use `experimental_backgroundImage` for linear gradients:**
+
+```tsx
+// Incorrect – third-party gradient library
+<LinearGradient colors={['#000', '#fff']} />
+
+// Correct – native CSS gradient syntax
+<View
+  style={{
+    experimental_backgroundImage: 'linear-gradient(to bottom, #000, #fff)',
+  }}
+/>
+```
+
+**Use CSS `boxShadow` string syntax for shadows:**
+
+```tsx
+// Incorrect – legacy shadow objects or elevation
+{ shadowColor: '#000', shadowOffset: { width: 0, height: 2 }, shadowOpacity: 0.1 }
+{ elevation: 4 }
+
+// Correct – CSS box-shadow syntax
+{ boxShadow: '0 2px 8px rgba(0, 0, 0, 0.1)' }
+```
+
+**Avoid multiple font sizes – use weight and color for emphasis:**
+
+```tsx
+// Incorrect – varying font sizes for hierarchy
+<Text style={{ fontSize: 18 }}>Title</Text>
+<Text style={{ fontSize: 14 }}>Subtitle</Text>
+<Text style={{ fontSize: 12 }}>Caption</Text>
+
+// Correct – consistent size, vary weight and color
+<Text style={{ fontWeight: '600' }}>Title</Text>
+<Text style={{ color: '#666' }}>Subtitle</Text>
+<Text style={{ color: '#999' }}>Caption</Text>
+```
+
+Limiting font sizes creates visual consistency. Use `fontWeight` (bold/semibold)
+and grayscale colors for hierarchy instead.
diff --git a/skills/vercel-react-view-transitions/AGENTS.md b/skills/vercel-react-view-transitions/AGENTS.md
new file mode 100644
index 00000000..8e213614
--- /dev/null
+++ b/skills/vercel-react-view-transitions/AGENTS.md
@@ -0,0 +1,955 @@
+# React View Transitions
+
+**Version 1.0.0**
+Vercel Engineering
+March 2026
+
+> **Note:**
+> This document is mainly for agents and LLMs to follow when implementing
+> view transitions in React applications. Humans may also find it useful,
+> but guidance here is optimized for automation and consistency by
+> AI-assisted workflows.
+
+---
+
+## Abstract
+
+Guide for implementing smooth, native-feeling animations using React's View Transition API. Covers the `<ViewTransition>` component, `addTransitionType`, CSS view transition pseudo-elements, shared element transitions, Suspense reveals, list reorder, directional navigation, and Next.js integration. Includes a step-by-step implementation workflow, ready-to-use CSS animation recipes, and common mistake warnings.
+
+---
+
+## Table of Contents
+
+1. [Core Reference](#when-to-animate)
+   - [When to Animate](#when-to-animate)
+   - [Availability](#availability)
+   - [Core Concepts](#core-concepts)
+   - [Styling with View Transition Classes](#styling-with-view-transition-classes)
+   - [Transition Types](#transition-types)
+   - [Shared Element Transitions](#shared-element-transitions)
+   - [Common Patterns](#common-patterns)
+   - [How Multiple VTs Interact](#how-multiple-vts-interact)
+   - [Next.js Integration](#nextjs-integration)
+   - [Accessibility](#accessibility)
+2. [Implementation Workflow](#implementation-workflow)
+   - [Step 1: Audit the App](#step-1-audit-the-app)
+   - [Step 2: Add CSS Recipes](#step-2-add-css-recipes)
+   - [Step 3: Isolate Persistent Elements](#step-3-isolate-persistent-elements)
+   - [Step 4: Add Directional Page Transitions](#step-4-add-directional-page-transitions)
+   - [Step 5: Add Suspense Reveals](#step-5-add-suspense-reveals)
+   - [Step 6: Add Shared Element Transitions](#step-6-add-shared-element-transitions)
+   - [Step 7: Verify Each Navigation Path](#step-7-verify-each-navigation-path)
+   - [Common Mistakes](#common-mistakes)
+3. [Patterns and Guidelines](#patterns-and-guidelines)
+4. [CSS Animation Recipes](#css-animation-recipes)
+5. [View Transitions in Next.js](#view-transitions-in-nextjs)
+
+---
+
+Animate between UI states using the browser's native `document.startViewTransition`. Declare *what* with `<ViewTransition>`, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.
+
+## When to Animate
+
+Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
+
+Implement **all** applicable patterns from this list, in this order:
+
+| Priority | Pattern | What it communicates |
+|----------|---------|---------------------|
+| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
+| 2 | **Suspense reveal** | "Data loaded" |
+| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
+| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
+| 5 | **Route change** (layout-level) | "Going to a new place" |
+
+This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
+
+### Choosing Animation Style
+
+| Context | Animation | Why |
+|---------|-----------|-----|
+| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
+| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
+| Suspense reveal | `enter`/`exit` string props | Content arriving |
+| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
+
+Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
+
+---
+
+## Availability
+
+- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
+- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
+- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation.
+
+---
+
+## Core Concepts
+
+### The `<ViewTransition>` Component
+
+```jsx
+import { ViewTransition } from 'react';
+
+<ViewTransition>
+  <Component />
+</ViewTransition>
+```
+
+React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
+
+### Animation Triggers
+
+| Trigger | When it fires |
+|---------|--------------|
+| **enter** | VT first inserted during a Transition |
+| **exit** | VT first removed during a Transition |
+| **update** | DOM mutations inside a VT. With nested VTs, mutation applies to the innermost one |
+| **share** | Named VT unmounts and another with same `name` mounts in same Transition |
+
+Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
+
+### Critical Placement Rule
+
+VT only activates enter/exit if it appears **before any DOM nodes**:
+
+```jsx
+// Works
+<ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition>
+
+// Broken — div wraps the VT
+<div><ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition></div>
+```
+
+---
+
+## Styling with View Transition Classes
+
+Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
+
+```jsx
+<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
+```
+
+If `default` is `"none"`, all triggers are off unless explicitly listed.
+
+### CSS Pseudo-Elements
+
+- `::view-transition-old(.class)` — outgoing snapshot
+- `::view-transition-new(.class)` — incoming snapshot
+- `::view-transition-group(.class)` — container
+- `::view-transition-image-pair(.class)` — old + new pair
+
+---
+
+## Transition Types
+
+Tag transitions with `addTransitionType` so VTs can pick different animations. Call it multiple times to stack types — different VTs in the tree react to different types:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  addTransitionType('select-item');
+  router.push('/detail/1');
+});
+```
+
+Map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
+  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
+  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
+  default="none"
+>
+  <Page />
+</ViewTransition>
+```
+
+`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
+  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+  default="none"
+>
+```
+
+**TypeScript:** `ViewTransitionClassPerType` requires a `default` key.
+
+### `router.back()` and Browser Back Button
+
+`router.back()` and the browser's back/forward buttons do **not** trigger view transitions (`popstate` is synchronous, incompatible with `startViewTransition`). Use `router.push()` with an explicit URL instead.
+
+### Types and Suspense
+
+Types are available during navigation but **not** during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
+
+---
+
+## Shared Element Transitions
+
+Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
+
+```jsx
+<ViewTransition name="hero-image">
+  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
+</ViewTransition>
+
+// Other view — same name
+<ViewTransition name="hero-image">
+  <img src="/full.jpg" />
+</ViewTransition>
+```
+
+- Only one VT with a given `name` can be mounted at a time — use unique names. Watch for reusable components: if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
+- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no pair forms, `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.
+- Never use fade-out exit on pages with shared morphs — use directional slide.
+
+---
+
+## Common Patterns
+
+### Enter/Exit
+
+```jsx
+{show && (
+  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
+)}
+```
+
+### List Reorder
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
+
+### Composing Shared Elements with List Identity
+
+Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element, use two nested `<ViewTransition>` boundaries:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                      {/* list identity */}
+    <Link href={`/items/${item.id}`}>
+      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
+        <Image src={item.image} />
+      </ViewTransition>
+      <p>{item.name}</p>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+### Force Re-Enter with `key`
+
+```jsx
+<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
+  <ResultsGrid />
+</ViewTransition>
+```
+
+**Caution:** Wrapping `<Suspense>` with key remounts the boundary and refetches.
+
+### Suspense Fallback to Content
+
+Simple cross-fade:
+```jsx
+<ViewTransition>
+  <Suspense fallback={<Skeleton />}><Content /></Suspense>
+</ViewTransition>
+```
+
+Directional reveal:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+</Suspense>
+```
+
+---
+
+## How Multiple VTs Interact
+
+Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions don't compete.
+
+### Use `default="none"` Liberally
+
+Without it, every VT fires the browser cross-fade on **every** transition. Always use `default="none"` and explicitly enable only desired triggers.
+
+### Two Patterns Coexist
+
+**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
+**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
+
+They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts.
+
+### Nested VT Limitation
+
+When a parent VT exits, nested VTs inside it do **not** fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See [react#36135](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
+
+---
+
+## Next.js Integration
+
+See the [View Transitions in Next.js](#view-transitions-in-nextjs) section below.
+
+---
+
+## Accessibility
+
+Always add reduced motion CSS to your global stylesheet:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
+
+---
+
+# Implementation Workflow
+
+**Follow these steps in order.** Start with the audit — do not skip it. Copy the CSS recipes from the CSS Recipes section below — do not write your own animation CSS.
+
+## Step 1: Audit the App
+
+Before writing any code, scan the codebase thoroughly. Search for:
+
+- **Every `<Link>` and `router.push`** — open every file that contains one
+- **Every `<Suspense>` boundary** — check what its fallback renders
+- **Every page/route component** — each needs a VT placement decision
+- **Persistent elements** (headers, navbars, sidebars) — need `viewTransitionName` isolation
+- **Shared visual elements** on both source and target views
+- **Skeleton-to-content control pairs** — if a fallback renders a control that also exists in the real content, both need a matching `viewTransitionName`
+
+Then classify every navigation and produce a navigation map:
+
+```
+| Route           | Navigates to         | Direction    | VT pattern            |
+|-----------------|----------------------|--------------|-----------------------|
+| /               | /detail/[id]         | forward      | directional slide     |
+| /detail/[id]    | /                    | back         | directional slide     |
+| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
+| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
+| (Suspense)      | (content loads)      | —            | slide-up reveal       |
+```
+
+For each shared element (`name` prop), note where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`.
+
+## Step 2: Add CSS Recipes
+
+Copy the **complete** CSS recipe set from the CSS Animation Recipes section below into your global stylesheet. Don't write your own — the recipes handle staggered timing, motion blur, and reduced motion.
+
+## Step 3: Isolate Persistent Elements
+
+```jsx
+<header style={{ viewTransitionName: "site-header" }}>...</header>
+```
+
+```css
+::view-transition-group(site-header) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround instead.
+
+## Step 4: Add Directional Page Transitions
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  router.push('/detail/1');
+});
+```
+
+Wrap each **page component** (not layout) in a type-keyed VT:
+
+```jsx
+<ViewTransition
+  enter={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
+  exit={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
+  default="none"
+>
+  <div>...page content...</div>
+</ViewTransition>
+```
+
+Extract into a reusable component so every page doesn't repeat the type map:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+**Rules:** Always pair `enter` with `exit`. Always include `default: "none"`. Place in page components, not layouts. Only use directional slides for hierarchical navigation or ordered sequences (prev/next).
+
+## Step 5: Add Suspense Reveals
+
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><AsyncContent /></ViewTransition>
+</Suspense>
+```
+
+Use `default="none"` on content VT. Use simple string props (not type maps) — Suspense resolves have no type.
+
+## Step 6: Add Shared Element Transitions
+
+```jsx
+// Source view
+<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
+  <Image src={photo.src} ... />
+</ViewTransition>
+
+// Target view — same name
+<ViewTransition name={`photo-${photo.id}`} share="morph">
+  <Image src={photo.src} ... />
+</ViewTransition>
+```
+
+When list items contain shared elements, compose both patterns — two independent layers:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                        {/* list identity */}
+    <Link href={`/detail/${item.id}`}>
+      <ViewTransition name={`item-${item.id}`} share="morph" default="none">  {/* shared element */}
+        <Image src={item.image} ... />
+      </ViewTransition>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+**Rules:** Names must be globally unique. Add `default="none"` on list-side shared elements.
+
+## Step 7: Verify Each Navigation Path
+
+Walk through every row in the navigation map from Step 1:
+
+- Does the VT mount/unmount, or stay mounted (same-route)?
+- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?
+- Does `default="none"` block an animation you actually want?
+- Do persistent elements stay static?
+- Do Suspense reveals animate independently from directional navigations?
+
+---
+
+## Common Mistakes
+
+- **Bare VT without `default="none"`** — fires cross-fade on every transition
+- **Directional VT in a layout** — layouts persist, enter/exit won't fire on route changes
+- **Fade-out exit with shared morphs** — conflicts with morph, use directional slide
+- **Writing custom animation CSS** — use the recipes
+- **Missing `default: "none"` in type-keyed objects** — TypeScript requires it, fallback is `"auto"`
+- **Type maps on Suspense reveals** — Suspense resolves have no type, use string props
+- **Raw `viewTransitionName` CSS to trigger animations** — React only starts view transitions when `<ViewTransition>` components are in the tree. Bare `viewTransitionName` is for isolating elements, not triggering animations.
+- **`update` trigger for same-route navigations** — nested VTs steal the mutation from the parent. Use `key` + `name` + `share` instead.
+- **Named VT in a reusable component** — if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer.
+- **`router.back()` for back navigation** — `router.back()` triggers synchronous `popstate`, incompatible with view transitions. Use `router.push()` with an explicit URL.
+
+For Next.js-specific steps, see the Next.js section below.
+
+---
+
+# Patterns and Guidelines
+
+## Searchable Grid with `useDeferredValue`
+
+```tsx
+'use client';
+
+import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';
+
+export default function SearchableGrid({ itemsPromise }) {
+  const [search, setSearch] = useState('');
+  const deferredSearch = useDeferredValue(search);
+
+  return (
+    <>
+      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
+      <ViewTransition>
+        <Suspense fallback={<GridSkeleton />}>
+          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
+        </Suspense>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Per-item named VTs in deferred lists trigger cross-fades on every keystroke. Fix with `default="none"`.
+
+## Card Expand/Collapse with `startTransition`
+
+```tsx
+'use client';
+
+import { useState, useRef, startTransition, ViewTransition } from 'react';
+
+export default function ItemGrid({ items }) {
+  const [expandedId, setExpandedId] = useState(null);
+  const scrollRef = useRef(0);
+
+  return expandedId ? (
+    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
+      <ItemDetail
+        item={items.find(i => i.id === expandedId)}
+        onClose={() => {
+          startTransition(() => {
+            setExpandedId(null);
+            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
+          });
+        }}
+      />
+    </ViewTransition>
+  ) : (
+    <div className="grid grid-cols-3 gap-4">
+      {items.map(item => (
+        <ViewTransition key={item.id} name={`item-${item.id}`}>
+          <ItemCard
+            item={item}
+            onSelect={() => {
+              scrollRef.current = window.scrollY;
+              startTransition(() => setExpandedId(item.id));
+            }}
+          />
+        </ViewTransition>
+      ))}
+    </div>
+  );
+}
+```
+
+## Cross-Fade Without Remount
+
+Omit `key` to trigger update (cross-fade) instead of exit + enter. Avoids Suspense remount:
+
+```jsx
+<ViewTransition><TabPanel tab={activeTab} /></ViewTransition>
+```
+
+## Isolate Elements from Parent Animations
+
+Persistent elements get captured in page's transition snapshot. Fix with `viewTransitionName`:
+
+```jsx
+<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
+```
+
+```css
+::view-transition-group(persistent-nav) { animation: none; z-index: 100; }
+```
+
+Same for floating elements (popovers, tooltips). Global fix: `::view-transition-group(*) { z-index: 100; }`
+
+## Shared Controls Between Skeleton and Content
+
+Give matching controls the same `viewTransitionName`. Don't put manual `viewTransitionName` on root DOM node inside `<ViewTransition>`.
+
+## Reusable Animated Collapse
+
+```jsx
+function AnimatedCollapse({ open, children }) {
+  if (!open) return null;
+  return <ViewTransition enter="expand-in" exit="collapse-out">{children}</ViewTransition>;
+}
+```
+
+## Preserve State with Activity
+
+```jsx
+<Activity mode={isVisible ? 'visible' : 'hidden'}>
+  <ViewTransition enter="slide-in" exit="slide-out"><Sidebar /></ViewTransition>
+</Activity>
+```
+
+## Exclude Elements with `useOptimistic`
+
+`useOptimistic` values update before snapshot, excluding them from animation. Use for controls; use committed state for animated content.
+
+---
+
+## View Transition Events
+
+Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return cleanup. `onShare` takes precedence.
+
+```jsx
+<ViewTransition
+  onEnter={(instance, types) => {
+    const anim = instance.new.animate(
+      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
+      { duration: 300, easing: 'ease-out' }
+    );
+    return () => anim.cancel();
+  }}
+>
+  <Component />
+</ViewTransition>
+```
+
+`instance`: `.old`, `.new`, `.group`, `.imagePair`, `.name`
+
+---
+
+## Animation Timing
+
+| Interaction | Duration |
+|------------|----------|
+| Direct toggle | 100–200ms |
+| Route transition | 150–250ms |
+| Suspense reveal | 200–400ms |
+| Shared element morph | 300–500ms |
+
+---
+
+## Troubleshooting
+
+**VT not activating:** Ensure VT comes before any DOM node. Ensure `startTransition`.
+
+**"Two VTs with same name":** Names must be globally unique. Use IDs.
+
+**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead.
+
+**Only updates animate:** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
+
+**Layout VT prevents page VTs from animating:** Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping `{children}`, page-level enter/exit will silently not work. Remove the layout VT.
+
+**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
+
+**Backdrop-blur flickers:** `::view-transition-old(name) { display: none }` + `::view-transition-new(name) { animation: none }`.
+
+**`border-radius` lost:** Apply `border-radius` directly to captured element.
+
+**Batching:** Multiple updates during animation are batched (A→B→C→D becomes B→D).
+
+---
+
+# CSS Animation Recipes
+
+Ready-to-use CSS for `<ViewTransition>` props. Copy into global stylesheet.
+
+## Timing Variables
+
+```css
+:root {
+  --duration-exit: 150ms;
+  --duration-enter: 210ms;
+  --duration-move: 400ms;
+}
+```
+
+### Shared Keyframes
+
+```css
+@keyframes fade {
+  from { filter: blur(3px); opacity: 0; }
+  to { filter: blur(0); opacity: 1; }
+}
+
+@keyframes slide {
+  from { translate: var(--slide-offset); }
+  to { translate: 0; }
+}
+
+@keyframes slide-y {
+  from { transform: translateY(var(--slide-y-offset, 10px)); }
+  to { transform: translateY(0); }
+}
+```
+
+## Fade
+
+```css
+::view-transition-old(.fade-out) {
+  animation: var(--duration-exit) ease-in fade reverse;
+}
+::view-transition-new(.fade-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
+}
+```
+
+## Slide (Vertical)
+
+```css
+::view-transition-old(.slide-down) {
+  animation:
+    var(--duration-exit) ease-out both fade reverse,
+    var(--duration-exit) ease-out both slide-y reverse;
+}
+::view-transition-new(.slide-up) {
+  animation:
+    var(--duration-enter) ease-in var(--duration-exit) both fade,
+    var(--duration-move) ease-in both slide-y;
+}
+```
+
+## Directional Navigation
+
+### Single-Class Approach
+
+```css
+::view-transition-old(.nav-forward) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-forward) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+
+::view-transition-old(.nav-back) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-back) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+```
+
+### Separate Enter/Exit Classes
+
+```css
+::view-transition-new(.slide-from-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+
+::view-transition-new(.slide-from-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+```
+
+## Shared Element Morph
+
+```css
+::view-transition-group(.morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-image-pair(.morph) {
+  animation-name: via-blur;
+}
+@keyframes via-blur {
+  30% { filter: blur(3px); }
+}
+```
+
+**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `<h3>` → `<h1>`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.
+
+## Text Morph
+
+Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
+
+```css
+::view-transition-group(.text-morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-old(.text-morph) {
+  display: none;
+}
+::view-transition-new(.text-morph) {
+  animation: none;
+  object-fit: none;
+  object-position: left top;
+}
+```
+
+## Scale
+
+```css
+::view-transition-old(.scale-out) {
+  animation: var(--duration-exit) ease-in scale-down;
+}
+::view-transition-new(.scale-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
+}
+@keyframes scale-down {
+  from { transform: scale(1); opacity: 1; }
+  to { transform: scale(0.85); opacity: 0; }
+}
+@keyframes scale-up {
+  from { transform: scale(0.85); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+## Persistent Element Isolation
+
+```css
+::view-transition-group(persistent-nav) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+### Backdrop-Blur Workaround
+
+```css
+::view-transition-old(persistent-nav) { display: none; }
+::view-transition-new(persistent-nav) { animation: none; }
+```
+
+## Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
+
+---
+
+# View Transitions in Next.js
+
+## Setup
+
+```js
+// next.config.js
+experimental: { viewTransition: true }
+```
+
+Wraps every `<Link>` navigation in `document.startViewTransition`. Use `default="none"` to prevent competing animations. Do **not** install `react@canary` — the App Router already bundles it.
+
+## Next.js Implementation Additions
+
+**After Step 2:** Enable the experimental flag.
+
+**Step 4:** Use `transitionTypes` on `<Link>` (if available — see availability note below):
+```tsx
+<Link href="/photo/1" transitionTypes={["nav-forward"]}>View</Link>
+<Link href="/" transitionTypes={["nav-back"]}>Back</Link>
+```
+
+**After Step 6:** For same-route dynamic segments, use `key` + `name` + `share` pattern.
+
+## Layout-Level ViewTransition
+
+Don't add a layout-level VT wrapping `{children}` if pages have their own VTs — nested VTs never fire enter/exit inside a parent VT, so page-level enter/exit will silently not work. Remove the layout VT entirely. A bare VT in layout works only if pages have no VTs of their own. Layouts persist across navigations — don't use type-keyed maps in layouts.
+
+## The `transitionTypes` Prop
+
+Works in Server Components, no wrapper needed:
+```tsx
+<Link href="/products/1" transitionTypes={['nav-forward']}>View</Link>
+```
+
+**Availability:** Requires `experimental.viewTransition: true`. Available in Next.js 15+ canary builds and Next.js 16+. If unavailable, use `startTransition` + `addTransitionType` + `router.push()`. To check: `grep -r "transitionTypes" node_modules/next/dist/`. Reserve manual `startTransition` for non-link interactions.
+
+## `loading.tsx` as Suspense Boundary
+
+Next.js `loading.tsx` files are implicit `<Suspense>` boundaries. Wrap the skeleton in `<ViewTransition exit="...">` in `loading.tsx`, and the content in `<ViewTransition enter="..." default="none">` in the page. This is the Next.js-idiomatic equivalent of explicit `<Suspense fallback={...}>`. Same rules apply: use simple string props (not type maps) since Suspense reveals fire without transition types.
+
+## Server-Side Filtering with `router.replace`
+
+For search/sort/filter that re-renders on the server (via URL params), use `startTransition` + `router.replace`. VTs activate because the update is inside `startTransition`. List items wrapped in `<ViewTransition key={item.id}>` animate reorder. This is the server-component alternative to the client-side `useDeferredValue` pattern.
+
+## Two-Layer Pattern (Directional + Suspense)
+
+Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):
+
+```tsx
+<ViewTransition
+  enter={{ "nav-forward": "slide-from-right", default: "none" }}
+  exit={{ "nav-forward": "slide-to-left", default: "none" }}
+  default="none"
+>
+  <div>
+    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+    </Suspense>
+  </div>
+</ViewTransition>
+```
+
+## Shared Elements Across Routes
+
+```tsx
+// List page
+<Link href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
+  <ViewTransition name={`product-${product.id}`}>
+    <Image src={product.image} alt={product.name} width={400} height={300} />
+  </ViewTransition>
+</Link>
+
+// Detail page — same name
+<ViewTransition name={`product-${product.id}`}>
+  <Image src={product.image} alt={product.name} width={800} height={600} />
+</ViewTransition>
+```
+
+## Same-Route Dynamic Segment Transitions
+
+Page stays mounted on dynamic segment change — enter/exit never fire. Use `key` + `name` + `share`:
+
+```tsx
+<Suspense fallback={<Skeleton />}>
+  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
+    <Content slug={slug} />
+  </ViewTransition>
+</Suspense>
+```
+
+## Server Components
+
+- `<ViewTransition>` works in Server and Client Components
+- `<Link transitionTypes>` works in Server Components
+- `addTransitionType` and programmatic nav require Client Components
diff --git a/skills/vercel-react-view-transitions/README.md b/skills/vercel-react-view-transitions/README.md
new file mode 100644
index 00000000..9f29bed9
--- /dev/null
+++ b/skills/vercel-react-view-transitions/README.md
@@ -0,0 +1,42 @@
+# React View Transitions Skill
+
+An agent skill for implementing smooth, native-feeling animations using React's View Transition API.
+
+## What This Skill Covers
+
+- **`<ViewTransition>` component** — animation triggers (enter, exit, update, share), placement rules, View Transition Classes
+- **`addTransitionType`** — tagging transitions for directional or context-specific animations
+- **Shared element transitions** — morphing elements across different views
+- **View Transition Events** — imperative JavaScript animations via the Web Animations API
+- **CSS pseudo-elements** — `::view-transition-old`, `::view-transition-new`, `::view-transition-group`
+- **Next.js integration** — `experimental.viewTransition`, the `transitionTypes` prop on `next/link`, App Router patterns
+- **Accessibility** — `prefers-reduced-motion` handling
+- **Ready-to-use CSS recipes** — fade, slide, scale, directional navigation
+
+## Skill Structure
+
+```
+react-view-transitions/
+├── SKILL.md                      # Core skill (always loaded)
+├── AGENTS.md                     # Full compiled document (all references expanded)
+└── references/
+    ├── implementation.md         # Step-by-step implementation workflow
+    ├── patterns.md               # Real-world patterns, events API, troubleshooting
+    ├── nextjs.md                 # Next.js-specific patterns
+    └── css-recipes.md            # Copy-paste CSS animations
+```
+
+## Installation
+
+Install via [skills.sh](https://skills.sh):
+
+```bash
+npx skills install https://github.com/vercel-labs/react-view-transitions-skill
+```
+
+## Resources
+
+- [React `<ViewTransition>` docs](https://react.dev/reference/react/ViewTransition)
+- [React `addTransitionType` docs](https://react.dev/reference/react/addTransitionType)
+- [Next.js `viewTransition` config](https://nextjs.org/docs/app/api-reference/config/next-config-js/viewTransition)
+- [Next.js App Router Playground (view transitions)](https://github.com/vercel/next-app-router-playground/tree/main/app/view-transitions) — Vercel's reference implementation
diff --git a/skills/vercel-react-view-transitions/SKILL.md b/skills/vercel-react-view-transitions/SKILL.md
new file mode 100644
index 00000000..dcecd8e3
--- /dev/null
+++ b/skills/vercel-react-view-transitions/SKILL.md
@@ -0,0 +1,320 @@
+---
+name: vercel-react-view-transitions
+description: Guide for implementing smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.
+license: MIT
+metadata:
+  author: vercel
+  version: "1.0.0"
+---
+
+# React View Transitions
+
+Animate between UI states using the browser's native `document.startViewTransition`. Declare *what* with `<ViewTransition>`, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.
+
+## When to Animate
+
+Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
+
+Implement **all** applicable patterns from this list, in this order:
+
+| Priority | Pattern | What it communicates |
+|----------|---------|---------------------|
+| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
+| 2 | **Suspense reveal** | "Data loaded" |
+| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
+| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
+| 5 | **Route change** (layout-level) | "Going to a new place" |
+
+This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
+
+### Choosing Animation Style
+
+| Context | Animation | Why |
+|---------|-----------|-----|
+| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
+| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
+| Suspense reveal | `enter`/`exit` string props | Content arriving |
+| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
+
+Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
+
+---
+
+## Availability
+
+- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
+- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
+- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
+
+---
+
+## Implementation Workflow
+
+When adding view transitions to an existing app, **follow `references/implementation.md` step by step.** Start with the audit — do not skip it. Copy the CSS recipes from `references/css-recipes.md` into the global stylesheet — do not write your own animation CSS.
+
+---
+
+## Core Concepts
+
+### The `<ViewTransition>` Component
+
+```jsx
+import { ViewTransition } from 'react';
+
+<ViewTransition>
+  <Component />
+</ViewTransition>
+```
+
+React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
+
+### Animation Triggers
+
+| Trigger | When it fires |
+|---------|--------------|
+| **enter** | `<ViewTransition>` first inserted during a Transition |
+| **exit** | `<ViewTransition>` first removed during a Transition |
+| **update** | DOM mutations inside a `<ViewTransition>`. With nested VTs, mutation applies to the innermost one |
+| **share** | Named VT unmounts and another with same `name` mounts in the same Transition |
+
+Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
+
+### Critical Placement Rule
+
+`<ViewTransition>` only activates enter/exit if it appears **before any DOM nodes**:
+
+```jsx
+// Works
+<ViewTransition enter="auto" exit="auto">
+  <div>Content</div>
+</ViewTransition>
+
+// Broken — div wraps the VT, suppressing enter/exit
+<div>
+  <ViewTransition enter="auto" exit="auto">
+    <div>Content</div>
+  </ViewTransition>
+</div>
+```
+
+---
+
+## Styling with View Transition Classes
+
+### Props
+
+Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
+
+```jsx
+<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
+```
+
+If `default` is `"none"`, all triggers are off unless explicitly listed.
+
+### CSS Pseudo-Elements
+
+- `::view-transition-old(.class)` — outgoing snapshot
+- `::view-transition-new(.class)` — incoming snapshot
+- `::view-transition-group(.class)` — container
+- `::view-transition-image-pair(.class)` — old + new pair
+
+See `references/css-recipes.md` for ready-to-use animation recipes.
+
+---
+
+## Transition Types
+
+Tag transitions with `addTransitionType` so VTs can pick different animations based on context. Call it multiple times to stack types — different VTs in the tree react to different types:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  addTransitionType('select-item');
+  router.push('/detail/1');
+});
+```
+
+Pass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
+  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
+  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
+  default="none"
+>
+  <Page />
+</ViewTransition>
+```
+
+`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
+  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+  default="none"
+>
+```
+
+**TypeScript:** `ViewTransitionClassPerType` requires a `default` key in the object.
+
+For apps with multiple pages, extract the type-keyed VT into a reusable wrapper:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+### `router.back()` and Browser Back Button
+
+`router.back()` and the browser's back/forward buttons do **not** trigger view transitions (`popstate` is synchronous, incompatible with `startViewTransition`). Use `router.push()` with an explicit URL instead.
+
+### Types and Suspense
+
+Types are available during navigation but **not** during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
+
+---
+
+## Shared Element Transitions
+
+Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
+
+```jsx
+<ViewTransition name="hero-image">
+  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
+</ViewTransition>
+
+// On the other view — same name
+<ViewTransition name="hero-image">
+  <img src="/full.jpg" />
+</ViewTransition>
+```
+
+- Only one VT with a given `name` can be mounted at a time — use unique names (`photo-${id}`). Watch for reusable components: if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
+- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no matching pair forms (e.g., the target page doesn't have the same name), `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.
+- Never use a fade-out exit on pages with shared morphs — use a directional slide instead.
+
+---
+
+## Common Patterns
+
+### Enter/Exit
+
+```jsx
+{show && (
+  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
+)}
+```
+
+### List Reorder
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
+
+### Composing Shared Elements with List Identity
+
+Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested `<ViewTransition>` boundaries:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                      {/* list identity */}
+    <Link href={`/items/${item.id}`}>
+      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
+        <Image src={item.image} />
+      </ViewTransition>
+      <p>{item.name}</p>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter animations. The inner VT handles the cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+### Force Re-Enter with `key`
+
+```jsx
+<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
+  <ResultsGrid />
+</ViewTransition>
+```
+
+**Caution:** If wrapping `<Suspense>`, changing `key` remounts the boundary and refetches.
+
+### Suspense Fallback to Content
+
+Simple cross-fade:
+```jsx
+<ViewTransition>
+  <Suspense fallback={<Skeleton />}><Content /></Suspense>
+</ViewTransition>
+```
+
+Directional reveal:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+</Suspense>
+```
+
+For more patterns, see `references/patterns.md`.
+
+---
+
+## How Multiple VTs Interact
+
+Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions (navigation vs later Suspense resolve) don't compete.
+
+### Use `default="none"` Liberally
+
+Without it, every VT fires the browser cross-fade on **every** transition — Suspense resolves, `useDeferredValue` updates, background revalidations. Always use `default="none"` and explicitly enable only desired triggers.
+
+### Two Patterns Coexist
+
+**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
+**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
+
+They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts.
+
+### Nested VT Limitation
+
+When a parent VT exits, nested VTs inside it do **not** fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See [react#36135](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
+
+---
+
+## Next.js Integration
+
+For Next.js setup (`experimental.viewTransition` flag, `transitionTypes` prop on `next/link`, App Router patterns, Server Components), see `references/nextjs.md`.
+
+---
+
+## Accessibility
+
+Always add the reduced motion CSS from `references/css-recipes.md` to your global stylesheet.
+
+---
+
+## Reference Files
+
+- **`references/implementation.md`** — Step-by-step implementation workflow.
+- **`references/patterns.md`** — Patterns, animation timing, events API, troubleshooting.
+- **`references/css-recipes.md`** — Ready-to-use CSS animation recipes.
+- **`references/nextjs.md`** — Next.js App Router patterns and Server Component details.
+
+## Full Compiled Document
+
+For the complete guide with all reference files expanded: `AGENTS.md`
diff --git a/skills/vercel-react-view-transitions/metadata.json b/skills/vercel-react-view-transitions/metadata.json
new file mode 100644
index 00000000..aabe3e14
--- /dev/null
+++ b/skills/vercel-react-view-transitions/metadata.json
@@ -0,0 +1,12 @@
+{
+  "version": "1.0.0",
+  "organization": "Vercel Engineering",
+  "date": "March 2026",
+  "abstract": "Guide for implementing smooth, native-feeling animations using React's View Transition API. Covers the <ViewTransition> component, addTransitionType, CSS view transition pseudo-elements, shared element transitions, JavaScript animations via Web Animations API, and Next.js integration including the transitionTypes prop on next/link. Includes ready-to-use CSS animation recipes and real-world patterns from production Next.js apps.",
+  "references": [
+    "https://react.dev/reference/react/ViewTransition",
+    "https://react.dev/reference/react/addTransitionType",
+    "https://nextjs.org/docs/app/api-reference/config/next-config-js/viewTransition",
+    "https://github.com/vercel/next-app-router-playground/tree/main/app/view-transitions"
+  ]
+}
diff --git a/skills/vercel-react-view-transitions/references/css-recipes.md b/skills/vercel-react-view-transitions/references/css-recipes.md
new file mode 100644
index 00000000..f9c1fca5
--- /dev/null
+++ b/skills/vercel-react-view-transitions/references/css-recipes.md
@@ -0,0 +1,242 @@
+# CSS Animation Recipes
+
+Ready-to-use CSS for `<ViewTransition>` props. Copy into your global stylesheet.
+
+---
+
+## Timing Variables
+
+```css
+:root {
+  --duration-exit: 150ms;
+  --duration-enter: 210ms;
+  --duration-move: 400ms;
+}
+```
+
+### Shared Keyframes
+
+```css
+@keyframes fade {
+  from { filter: blur(3px); opacity: 0; }
+  to { filter: blur(0); opacity: 1; }
+}
+
+@keyframes slide {
+  from { translate: var(--slide-offset); }
+  to { translate: 0; }
+}
+
+@keyframes slide-y {
+  from { transform: translateY(var(--slide-y-offset, 10px)); }
+  to { transform: translateY(0); }
+}
+```
+
+---
+
+## Fade
+
+```css
+::view-transition-old(.fade-out) {
+  animation: var(--duration-exit) ease-in fade reverse;
+}
+::view-transition-new(.fade-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
+}
+```
+
+Usage: `<ViewTransition enter="fade-in" exit="fade-out" />`
+
+---
+
+## Slide (Vertical)
+
+```css
+::view-transition-old(.slide-down) {
+  animation:
+    var(--duration-exit) ease-out both fade reverse,
+    var(--duration-exit) ease-out both slide-y reverse;
+}
+::view-transition-new(.slide-up) {
+  animation:
+    var(--duration-enter) ease-in var(--duration-exit) both fade,
+    var(--duration-move) ease-in both slide-y;
+}
+```
+
+Usage:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition default="none" enter="slide-up"><Content /></ViewTransition>
+</Suspense>
+```
+
+---
+
+## Directional Navigation
+
+### Separate Enter/Exit Classes
+
+```css
+::view-transition-new(.slide-from-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+
+::view-transition-new(.slide-from-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+```
+
+### Single-Class Approach
+
+```css
+::view-transition-old(.nav-forward) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-forward) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+
+::view-transition-old(.nav-back) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-back) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+```
+
+---
+
+## Shared Element Morph
+
+```css
+::view-transition-group(.morph) {
+  animation-duration: var(--duration-move);
+}
+
+::view-transition-image-pair(.morph) {
+  animation-name: via-blur;
+}
+
+@keyframes via-blur {
+  30% { filter: blur(3px); }
+}
+```
+
+Usage: `<ViewTransition name={`product-${id}`} share="morph" />`
+
+**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `<h3>` → `<h1>`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.
+
+## Text Morph
+
+Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
+
+```css
+::view-transition-group(.text-morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-old(.text-morph) {
+  display: none;
+}
+::view-transition-new(.text-morph) {
+  animation: none;
+  object-fit: none;
+  object-position: left top;
+}
+```
+
+Usage: `<ViewTransition name={`title-${id}`} share="text-morph" />`
+
+---
+
+## Scale
+
+```css
+::view-transition-old(.scale-out) {
+  animation: var(--duration-exit) ease-in scale-down;
+}
+::view-transition-new(.scale-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
+}
+
+@keyframes scale-down {
+  from { transform: scale(1); opacity: 1; }
+  to { transform: scale(0.85); opacity: 0; }
+}
+@keyframes scale-up {
+  from { transform: scale(0.85); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+Usage: `<ViewTransition enter="scale-in" exit="scale-out" />`
+
+---
+
+## Persistent Element Isolation
+
+```css
+::view-transition-group(persistent-nav) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+### Backdrop-Blur Workaround
+
+For elements with `backdrop-filter`, hide the old snapshot to avoid flash:
+
+```css
+::view-transition-old(persistent-nav) {
+  display: none;
+}
+::view-transition-new(persistent-nav) {
+  animation: none;
+}
+```
+
+---
+
+## Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```
diff --git a/skills/vercel-react-view-transitions/references/implementation.md b/skills/vercel-react-view-transitions/references/implementation.md
new file mode 100644
index 00000000..e4207c9b
--- /dev/null
+++ b/skills/vercel-react-view-transitions/references/implementation.md
@@ -0,0 +1,182 @@
+# Implementation Workflow
+
+Follow these steps in order when adding view transitions to an app. Each step builds on the previous one.
+
+## Step 1: Audit the App
+
+Before writing any code, scan the codebase thoroughly. Search for:
+
+- **Every `<Link>` and `router.push`** — these are your navigation triggers. Open every file that contains one.
+- **Every `<Suspense>` boundary** — each one is a candidate for a reveal animation. Check what its fallback renders.
+- **Every page/route component** — list them all. Each page needs a VT placement decision.
+- **Persistent elements** — headers, navbars, sidebars, sticky controls that stay on screen across navigations. These need `viewTransitionName` isolation.
+- **Shared visual elements** — images, cards, or avatars that appear on both a source and target view (e.g., a thumbnail in a list and the same image on a detail page).
+- **Skeleton-to-content control pairs** — if a Suspense fallback renders a control (search input, tab bar) that also exists in the real content, both need a matching `viewTransitionName`.
+
+Then classify every navigation and produce a navigation map:
+
+```
+| Route           | Navigates to         | Direction    | VT pattern            |
+|-----------------|----------------------|--------------|-----------------------|
+| /               | /detail/[id]         | forward      | directional slide     |
+| /detail/[id]    | /                    | back         | directional slide     |
+| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
+| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
+| (Suspense)      | (content loads)      | —            | slide-up reveal       |
+```
+
+For each shared element (`name` prop), note every navigation where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`.
+
+## Step 2: Add CSS Recipes
+
+Copy the **complete** CSS recipe set from `css-recipes.md` into your global stylesheet. This includes timing variables, shared keyframes, fade, slide (vertical), directional navigation (forward/back), shared element morph, persistent element isolation, and reduced motion.
+
+Do not write your own animation CSS — the recipes handle staggered timing, motion blur on morphs, and reduced motion that are easy to get wrong. You can customize timing variables (`--duration-exit`, `--duration-enter`, `--duration-move`) after the initial setup.
+
+## Step 3: Isolate Persistent Elements
+
+For every persistent element identified in Step 1, add a `viewTransitionName` style to pull it out of the page content's transition snapshot:
+
+```jsx
+<header style={{ viewTransitionName: "site-header" }}>...</header>
+```
+
+Then add the persistent element isolation CSS from `css-recipes.md` (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the backdrop-blur workaround from `css-recipes.md` instead.
+
+If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
+
+## Step 4: Add Directional Page Transitions
+
+For hierarchical navigations identified in Step 1, tag the navigation direction using `addTransitionType` inside `startTransition`:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  router.push('/detail/1');
+});
+```
+
+Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>`:
+
+```jsx
+<ViewTransition
+  enter={{
+    "nav-forward": "nav-forward",
+    "nav-back": "nav-back",
+    default: "none",
+  }}
+  exit={{
+    "nav-forward": "nav-forward",
+    "nav-back": "nav-back",
+    default: "none",
+  }}
+  default="none"
+>
+  <div>...page content...</div>
+</ViewTransition>
+```
+
+The `nav-forward` and `nav-back` CSS classes from `css-recipes.md` produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
+
+Extract this into a reusable component so every page doesn't repeat the verbose type map:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+This also becomes the single place to adjust if you add new transition types later.
+
+**Rules:**
+- Always pair `enter` with `exit` — without an exit animation, the old page disappears instantly while the new one animates in.
+- Always include `default: "none"` in type map objects and `default="none"` on the component — otherwise it fires on every transition.
+- Place the directional `<ViewTransition>` in each page component, not in a layout. Layouts persist across navigations and never trigger enter/exit.
+- Only use directional slides for hierarchical navigation or ordered sequences (prev/next). Lateral/sibling navigation (tab-to-tab) should use a bare `<ViewTransition>` (cross-fade) or `default="none"`.
+
+## Step 5: Add Suspense Reveals
+
+For every `<Suspense>` boundary identified in Step 1, wrap the fallback and content in separate `<ViewTransition>`s:
+
+```jsx
+<Suspense
+  fallback={
+    <ViewTransition exit="slide-down">
+      <Skeleton />
+    </ViewTransition>
+  }
+>
+  <ViewTransition enter="slide-up" default="none">
+    <AsyncContent />
+  </ViewTransition>
+</Suspense>
+```
+
+This example uses `slide-down` / `slide-up` for directional vertical motion. For a simpler reveal, a bare `<ViewTransition>` around the `<Suspense>` gives a cross-fade with zero configuration. Choose based on the spatial meaning — consult the "Choosing the Right Animation Style" table in the main skill file.
+
+**Rules:**
+- Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
+- Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
+
+## Step 6: Add Shared Element Transitions
+
+For every shared visual element identified in Step 1, add matching named `<ViewTransition>` wrappers on both the source and target views:
+
+```jsx
+// On the source view (e.g., list/grid page)
+<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
+  <Image src={photo.src} ... />
+</ViewTransition>
+
+// On the target view (e.g., detail page) — same name
+<ViewTransition name={`photo-${photo.id}`} share="morph">
+  <Image src={photo.src} ... />
+</ViewTransition>
+```
+
+The `share="morph"` class uses the morph recipe from `css-recipes.md` (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
+
+When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — see "Composing Shared Elements with List Identity" in `SKILL.md`.
+
+**Rules:**
+- Names must be globally unique — use prefixes like `photo-${id}`.
+- Add `default="none"` on list-side shared elements to prevent per-item cross-fades on filter/search updates.
+
+## Step 7: Verify Each Navigation Path
+
+Walk through every row in the navigation map from Step 1 and confirm:
+
+- Does the VT mount/unmount on this navigation, or does it stay mounted (same-route)?
+- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?
+- Does `default="none"` block an animation you actually want?
+- Do persistent elements stay static (not sliding with page content)?
+- Do Suspense reveals animate independently from directional navigations?
+
+If any path produces no animation or competing animations, revisit the relevant step.
+
+---
+
+## Common Mistakes
+
+- **Bare `<ViewTransition>` without props** — without `default="none"`, it fires the browser's default cross-fade on every transition (every navigation, every Suspense resolve, every revalidation). Always set `default="none"` and explicitly enable only the triggers you want.
+- **Directional `<ViewTransition>` in a layout** — layouts persist across navigations and never unmount/remount. `enter`/`exit` props won't fire on route changes. Place the outer type-keyed `<ViewTransition>` in each page component.
+- **Fade-out exit with shared element morphs** — the page dissolving conflicts with the morph. Use a directional slide exit instead.
+- **Writing custom animation CSS** — the recipes in `css-recipes.md` handle staggered timing, motion blur on morphs, and reduced motion. Copy them; don't reinvent them.
+- **Missing `default: "none"` in type-keyed objects** — TypeScript requires a `default` key, and without it the fallback is `"auto"` which fires on every transition.
+- **Type maps on Suspense reveals** — Suspense resolves fire as separate transitions with no type. Type-keyed props won't match — use simple string props instead.
+- **Raw `viewTransitionName` CSS to trigger animations** — React only calls `document.startViewTransition` when `<ViewTransition>` components are in the tree. A bare `viewTransitionName` style is for isolating elements from a parent's snapshot, not for triggering animations.
+- **`update` trigger for same-route navigations** — nested VTs inside the content steal the mutation from the parent, so `update` never fires on the outer VT. Use `key` + `name` + `share` instead.
+- **Named VT in a reusable component** — if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer.
+- **`router.back()` for back navigation** — `router.back()` triggers synchronous `popstate`, incompatible with view transitions. Use `router.push()` with an explicit URL.
+
+---
+
+For Next.js-specific implementation steps (config flag, `transitionTypes` on `<Link>`, same-route dynamic segments), see `nextjs.md`.
diff --git a/skills/vercel-react-view-transitions/references/nextjs.md b/skills/vercel-react-view-transitions/references/nextjs.md
new file mode 100644
index 00000000..06a96c7e
--- /dev/null
+++ b/skills/vercel-react-view-transitions/references/nextjs.md
@@ -0,0 +1,176 @@
+# View Transitions in Next.js
+
+## Setup
+
+`<ViewTransition>` works out of the box for `startTransition`/`Suspense` updates. To also animate `<Link>` navigations:
+
+```js
+// next.config.js
+const nextConfig = {
+  experimental: { viewTransition: true },
+};
+module.exports = nextConfig;
+```
+
+This wraps every `<Link>` navigation in `document.startViewTransition`. Any VT with `default="auto"` fires on **every** link click — use `default="none"` to prevent competing animations.
+
+Do **not** install `react@canary` — see SKILL.md "Availability" for details.
+
+---
+
+## Next.js Implementation Additions
+
+When following `implementation.md`, apply these additions:
+
+**After Step 2:** Enable the experimental flag above.
+
+**Step 4:** Use `transitionTypes` on `<Link>` — see "The `transitionTypes` Prop" section below for usage and availability.
+
+**After Step 6:** For same-route dynamic segments (e.g., `/collection/[slug]`), use the `key` + `name` + `share` pattern — see Same-Route Dynamic Segment Transitions below.
+
+---
+
+## Layout-Level ViewTransition
+
+**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** Nested VTs never fire enter/exit when inside a parent VT — page-level enter/exit will silently not work. Remove the layout VT entirely.
+
+A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
+
+**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts.
+
+---
+
+## The `transitionTypes` Prop on `next/link`
+
+No wrapper component needed, works in Server Components:
+
+```tsx
+<Link href="/products/1" transitionTypes={['transition-to-detail']}>View Product</Link>
+```
+
+Replaces the manual pattern of `onNavigate` + `startTransition` + `addTransitionType` + `router.push()`. Reserve manual `startTransition` for non-link interactions (buttons, forms).
+
+**Availability:** `transitionTypes` requires `experimental.viewTransition: true` and is available in Next.js 15+ canary builds and Next.js 16+. If unavailable, use `startTransition` + `addTransitionType` + `router.push()` (see Programmatic Navigation below). To check: `grep -r "transitionTypes" node_modules/next/dist/` — if no results, fall back to programmatic navigation.
+
+---
+
+## Programmatic Navigation
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { startTransition, addTransitionType } from 'react';
+
+function handleNavigate(href: string) {
+  const router = useRouter();
+  startTransition(() => {
+    addTransitionType('nav-forward');
+    router.push(href);
+  });
+}
+```
+
+---
+
+## Server-Side Filtering with `router.replace`
+
+For search/sort/filter that re-renders on the server (via URL params), use `startTransition` + `router.replace`. VTs activate because the state update is inside `startTransition`:
+
+```tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { startTransition } from 'react';
+
+function handleSort(sort: string) {
+  const router = useRouter();
+  startTransition(() => {
+    router.replace(`?sort=${sort}`);
+  });
+}
+```
+
+List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side `useDeferredValue` pattern in `patterns.md`.
+
+---
+
+## Two-Layer Pattern (Directional + Suspense)
+
+Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):
+
+```tsx
+<ViewTransition
+  enter={{ "nav-forward": "slide-from-right", default: "none" }}
+  exit={{ "nav-forward": "slide-to-left", default: "none" }}
+  default="none"
+>
+  <div>
+    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+    </Suspense>
+  </div>
+</ViewTransition>
+```
+
+---
+
+## `loading.tsx` as Suspense Boundary
+
+Next.js `loading.tsx` is an implicit `<Suspense>` boundary. Wrap the skeleton in `<ViewTransition exit="...">` in `loading.tsx`, and the content in `<ViewTransition enter="..." default="none">` in the page:
+
+```tsx
+// loading.tsx
+<ViewTransition exit="slide-down"><PhotoGridSkeleton /></ViewTransition>
+
+// page.tsx
+<ViewTransition enter="slide-up" default="none"><PhotoGrid photos={photos} /></ViewTransition>
+```
+
+Same rules as explicit `<Suspense>`: use simple string props (not type maps) since Suspense reveals fire without transition types.
+
+---
+
+## Shared Elements Across Routes
+
+```tsx
+// List page
+{products.map((product) => (
+  <Link key={product.id} href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
+    <ViewTransition name={`product-${product.id}`}>
+      <Image src={product.image} alt={product.name} width={400} height={300} />
+    </ViewTransition>
+  </Link>
+))}
+
+// Detail page — same name
+<ViewTransition name={`product-${product.id}`}>
+  <Image src={product.image} alt={product.name} width={800} height={600} />
+</ViewTransition>
+```
+
+---
+
+## Same-Route Dynamic Segment Transitions
+
+When navigating between dynamic segments of the same route (e.g., `/collection/[slug]`), the page stays mounted — enter/exit never fire. Use `key` + `name` + `share`:
+
+```tsx
+<Suspense fallback={<Skeleton />}>
+  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
+    <Content slug={slug} />
+  </ViewTransition>
+</Suspense>
+```
+
+- `key={slug}` forces unmount/remount on change
+- `name` + `share="auto"` creates a shared element crossfade
+- VT inside `<Suspense>` (without keying Suspense) keeps old content visible during loading
+
+---
+
+## Server Components
+
+- `<ViewTransition>` works in both Server and Client Components
+- `<Link transitionTypes>` works in Server Components — no `'use client'` needed
+- `addTransitionType` and `startTransition` for programmatic nav require Client Components
diff --git a/skills/vercel-react-view-transitions/references/patterns.md b/skills/vercel-react-view-transitions/references/patterns.md
new file mode 100644
index 00000000..6919ea4a
--- /dev/null
+++ b/skills/vercel-react-view-transitions/references/patterns.md
@@ -0,0 +1,262 @@
+# Patterns and Guidelines
+
+## Searchable Grid with `useDeferredValue`
+
+`useDeferredValue` makes filter updates a transition, activating `<ViewTransition>`:
+
+```tsx
+'use client';
+
+import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';
+
+export default function SearchableGrid({ itemsPromise }) {
+  const [search, setSearch] = useState('');
+  const deferredSearch = useDeferredValue(search);
+
+  return (
+    <>
+      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
+      <ViewTransition>
+        <Suspense fallback={<GridSkeleton />}>
+          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
+        </Suspense>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Per-item `<ViewTransition name={...}>` inside a deferred list triggers cross-fades on every keystroke. Fix with `default="none"`:
+
+```tsx
+{filteredItems.map(item => (
+  <ViewTransition key={item.id} name={`item-${item.id}`} share="morph" default="none">
+    <ItemCard item={item} />
+  </ViewTransition>
+))}
+```
+
+## Card Expand/Collapse with `startTransition`
+
+Toggle between grid and detail view with shared element morph:
+
+```tsx
+'use client';
+
+import { useState, useRef, startTransition, ViewTransition } from 'react';
+
+export default function ItemGrid({ items }) {
+  const [expandedId, setExpandedId] = useState(null);
+  const scrollRef = useRef(0);
+
+  return expandedId ? (
+    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
+      <ItemDetail
+        item={items.find(i => i.id === expandedId)}
+        onClose={() => {
+          startTransition(() => {
+            setExpandedId(null);
+            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
+          });
+        }}
+      />
+    </ViewTransition>
+  ) : (
+    <div className="grid grid-cols-3 gap-4">
+      {items.map(item => (
+        <ViewTransition key={item.id} name={`item-${item.id}`}>
+          <ItemCard
+            item={item}
+            onSelect={() => {
+              scrollRef.current = window.scrollY;
+              startTransition(() => setExpandedId(item.id));
+            }}
+          />
+        </ViewTransition>
+      ))}
+    </div>
+  );
+}
+```
+
+## Type-Safe Transition Helpers
+
+Use `as const` arrays and derived types to prevent ID clashes:
+
+```tsx
+const transitionTypes = ['default', 'transition-to-detail', 'transition-to-list'] as const;
+const animationTypes = ['auto', 'none', 'animate-slide-from-left', 'animate-slide-from-right'] as const;
+
+type TransitionType = (typeof transitionTypes)[number];
+type AnimationType = (typeof animationTypes)[number];
+type TransitionMap = { default: AnimationType } & Partial<Record<Exclude<TransitionType, 'default'>, AnimationType>>;
+
+export function HorizontalTransition({ children, enter, exit }: {
+  children: React.ReactNode;
+  enter: TransitionMap;
+  exit: TransitionMap;
+}) {
+  return <ViewTransition enter={enter} exit={exit}>{children}</ViewTransition>;
+}
+```
+
+## Cross-Fade Without Remount
+
+Omit `key` to trigger an update (cross-fade) instead of exit + enter. Avoids Suspense remount/refetch:
+
+```jsx
+<ViewTransition>
+  <TabPanel tab={activeTab} />
+</ViewTransition>
+```
+
+Use `key` when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel).
+
+## Isolate Elements from Parent Animations
+
+### Persistent Layout Elements
+
+Persistent elements (headers, navbars, sidebars) get captured in the page's transition snapshot. Fix with `viewTransitionName`:
+
+```jsx
+<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
+```
+
+Then add the persistent element isolation CSS from `css-recipes.md`. For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround from `css-recipes.md`.
+
+### Floating Elements
+
+Give popovers/tooltips their own `viewTransitionName`:
+
+```jsx
+<SelectPopover style={{ viewTransitionName: 'popover' }}>{options}</SelectPopover>
+```
+
+Global fix: see persistent element isolation in `css-recipes.md`.
+
+## Shared Controls Between Skeleton and Content
+
+Give matching controls in fallback and content the same `viewTransitionName`:
+
+```jsx
+// Fallback
+<input disabled placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
+// Content
+<input placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
+```
+
+Don't put manual `viewTransitionName` on the root DOM node inside `<ViewTransition>` — React's auto-generated name overrides it.
+
+## Reusable Animated Collapse
+
+```jsx
+function AnimatedCollapse({ open, children }) {
+  if (!open) return null;
+  return (
+    <ViewTransition enter="expand-in" exit="collapse-out">
+      {children}
+    </ViewTransition>
+  );
+}
+
+// Usage: toggle with startTransition
+<button onClick={() => startTransition(() => setOpen(o => !o))}>Toggle</button>
+<AnimatedCollapse open={open}><SectionContent /></AnimatedCollapse>
+```
+
+## Preserve State with Activity
+
+```jsx
+<Activity mode={isVisible ? 'visible' : 'hidden'}>
+  <ViewTransition enter="slide-in" exit="slide-out">
+    <Sidebar />
+  </ViewTransition>
+</Activity>
+```
+
+## Exclude Elements with `useOptimistic`
+
+`useOptimistic` values update before the transition snapshot, excluding them from animation. Use for controls (labels); use committed state for animated content:
+
+```tsx
+const [sort, setSort] = useState('newest');
+const [optimisticSort, setOptimisticSort] = useOptimistic(sort);
+
+function cycleSort() {
+  const nextSort = getNextSort(optimisticSort);
+  startTransition(() => {
+    setOptimisticSort(nextSort);  // before snapshot — no animation
+    setSort(nextSort);            // between snapshots — animates
+  });
+}
+
+<button>Sort: {LABELS[optimisticSort]}</button>
+{items.sort(comparators[sort]).map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+---
+
+## View Transition Events
+
+Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return a cleanup function. `onShare` takes precedence over `onEnter`/`onExit`.
+
+```jsx
+<ViewTransition
+  onEnter={(instance, types) => {
+    const anim = instance.new.animate(
+      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
+      { duration: 300, easing: 'ease-out' }
+    );
+    return () => anim.cancel();
+  }}
+>
+  <Component />
+</ViewTransition>
+```
+
+The `instance` object: `instance.old`, `instance.new`, `instance.group`, `instance.imagePair`, `instance.name`.
+
+The `types` array (second argument) lets you vary animation based on transition type.
+
+---
+
+## Animation Timing
+
+| Interaction | Duration |
+|------------|----------|
+| Direct toggle (expand/collapse) | 100–200ms |
+| Route transition (slide) | 150–250ms |
+| Suspense reveal (skeleton → content) | 200–400ms |
+| Shared element morph | 300–500ms |
+
+---
+
+## Troubleshooting
+
+**VT not activating:** Ensure `<ViewTransition>` comes before any DOM node. Ensure state update is inside `startTransition`.
+
+**"Two ViewTransition components with the same name":** Names must be globally unique. Use IDs: `name={`hero-${item.id}`}`.
+
+**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead. See SKILL.md "router.back() and Browser Back Button."
+
+**`flushSync` skips animations:** Use `startTransition` instead.
+
+**Only updates animate (no enter/exit):** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
+
+**Layout VT prevents page VTs from animating:** Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping `{children}`, page-level enter/exit will silently not work. Remove the layout VT.
+
+**List reorder not animating with `useOptimistic`:** Optimistic values resolve before snapshot. Use committed state for list order.
+
+**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
+
+**Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
+
+**Backdrop-blur flickers:** Use the backdrop-blur workaround from `css-recipes.md`.
+
+**`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
+
+**Skeleton controls slide away:** Give matching controls the same `viewTransitionName`.
+
+**Batching:** Multiple updates during animation are batched. A→B→C→D becomes B→D.
diff --git a/skills/web-design-guidelines/SKILL.md b/skills/web-design-guidelines/SKILL.md
new file mode 100644
index 00000000..ceae92ab
--- /dev/null
+++ b/skills/web-design-guidelines/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/conftest.py b/tests/conftest.py
new file mode 100644
index 00000000..e363e9ed
--- /dev/null
+++ b/tests/conftest.py
@@ -0,0 +1,7 @@
+import os
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(PROJECT_ROOT))
+os.chdir(PROJECT_ROOT)
diff --git a/tests/e2e/__init__.py b/tests/e2e/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/tests/e2e/_harness/__init__.py b/tests/e2e/_harness/__init__.py
new file mode 100644
index 00000000..d1f5a005
--- /dev/null
+++ b/tests/e2e/_harness/__init__.py
@@ -0,0 +1,37 @@
+"""Shared infrastructure for LIVE end-to-end tests.
+
+Private package (underscore-prefixed) so pytest doesn't collect it as
+a test module.
+
+Two concerns, two modules:
+  - :mod:`helpers` — drive the agent: ``build_agent``, ``run_scenario``.
+  - :mod:`trace`   — render what happened: ``format_agent_trace``,
+                     ``save_trace_log``, ``record_llm_calls``.
+
+Tests import from the package directly::
+
+    from tests.e2e._harness import build_agent, run_scenario, save_trace_log
+"""
+
+from tests.e2e._harness.helpers import build_agent, run_scenario
+from tests.e2e._harness.trace import (
+    TEST_LOG_DIR,
+    actions_called,
+    assert_action_called,
+    format_agent_trace,
+    record_action_calls,
+    record_llm_calls,
+    save_trace_log,
+)
+
+__all__ = [
+    "build_agent",
+    "run_scenario",
+    "actions_called",
+    "assert_action_called",
+    "format_agent_trace",
+    "record_action_calls",
+    "record_llm_calls",
+    "save_trace_log",
+    "TEST_LOG_DIR",
+]
diff --git a/tests/e2e/_harness/helpers.py b/tests/e2e/_harness/helpers.py
new file mode 100644
index 00000000..97c154f9
--- /dev/null
+++ b/tests/e2e/_harness/helpers.py
@@ -0,0 +1,269 @@
+"""Generic agent-driving infrastructure for LIVE end-to-end tests.
+
+Two public functions, both integration-agnostic:
+
+- ``build_agent(require=[...])`` — construct the real AgentBase, skip the
+  test if the LLM provider or any required integration isn't configured.
+- ``run_scenario(agent, user_message, ...)`` — send a chat through the
+  same entry point the CraftBot UI uses, drain the trigger queue, return
+  bridge status dicts. Captures every LLM call onto
+  ``agent._test_llm_calls`` for the trace logger to render afterwards.
+
+Event-loop note
+---------------
+
+Keep boot + react + assertions inside one ``asyncio.run`` call. The
+integration manager binds its async resources to the loop that
+``agent.boot()`` runs on; switching loops mid-test strands the bridge
+and ``react()`` silently exits early.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Callable
+
+import pytest
+
+# Module-level setup mirrors app/main.py registrations BEFORE importing AgentBase.
+os.environ.setdefault("GUI_MODE_ENABLED", "False")
+
+from agent_core import StateRegistry, ConfigRegistry  # noqa: E402
+from app.state.agent_state import STATE  # noqa: E402
+from app.config import (  # noqa: E402
+    get_project_root, get_llm_provider, get_api_key, get_base_url, get_llm_model,
+    get_vlm_provider, get_vlm_model,
+)
+
+StateRegistry.register(lambda: STATE)
+ConfigRegistry.register_workspace_root(str(get_project_root()))
+
+from app.agent_base import AgentBase  # noqa: E402
+from craftos_integrations import get_client, list_connected  # noqa: E402
+
+from tests.e2e._harness.trace import (  # noqa: E402
+    record_action_calls,
+    record_llm_calls,
+)
+
+
+def build_agent(*, require: list[str] | tuple[str, ...] = ()) -> AgentBase:
+    """Construct ``AgentBase`` the same way ``app/main.py`` does.
+
+    Skips the test (via ``pytest.skip``) when the LLM provider or any
+    integration in ``require`` isn't configured on this host, so the same
+    test file is safe to keep in the suite even on machines without those
+    credentials.
+    """
+    provider = get_llm_provider()
+    if not provider:
+        pytest.skip("no LLM provider configured in settings.json")
+    api_key = get_api_key(provider)
+    if not api_key and provider != "remote":
+        pytest.skip(f"no API key for provider {provider!r} in settings.json")
+    for pid in require:
+        if pid not in list_connected():
+            pytest.skip(f"integration {pid!r} not connected on this host.")
+
+    return AgentBase(
+        data_dir="app/data",
+        chroma_path="./chroma_db",
+        llm_provider=provider,
+        llm_api_key=api_key,
+        llm_base_url=get_base_url(provider),
+        llm_model=get_llm_model(),
+        vlm_provider=get_vlm_provider(),
+        vlm_model=get_vlm_model(),
+        deferred_init=False,
+    )
+
+
+async def run_scenario(
+    agent: AgentBase,
+    user_message: str | None = None,
+    *,
+    incoming_event: dict | None = None,
+    wait_for_incoming: bool = False,
+    expect_no_incoming: bool = False,
+    incoming_prompt: str | None = None,
+    incoming_filter: Callable[[dict], bool] | None = None,
+    incoming_timeout: float = 30.0,
+    platform: str | None = None,
+    wait_for: list[str] | tuple[str, ...] = (),
+    max_iterations: int = 20,
+    per_iter_timeout: float = 30.0,
+    ready_timeout: float = 45.0,
+) -> dict[str, dict]:
+    """Run one live scenario end-to-end.
+
+    Exactly one entry mode must be set:
+
+      - ``user_message`` — simulate the user typing a chat. Goes through
+        ``agent._handle_chat_message({"text": ...})`` — same call path
+        as the CraftBot UI.
+      - ``incoming_event`` — synthesize the payload an integration would
+        emit and fire ``agent._handle_external_event(payload)`` directly.
+        Bypasses the actual bridge listener — useful only when you want
+        to test the routing rules in isolation.
+      - ``wait_for_incoming`` — wait for the integration manager's real
+        on-message callback to fire ``_handle_external_event``. Use this
+        for true end-to-end: the test pauses until you (or someone else)
+        actually send a whatsapp message that the bridge picks up. Prints
+        ``incoming_prompt`` first if provided, applies ``incoming_filter``
+        to ignore irrelevant inbound events, and fails after
+        ``incoming_timeout`` seconds if nothing matching arrives.
+      - ``expect_no_incoming`` — mirror of ``wait_for_incoming``: prompt,
+        then wait the full ``incoming_timeout`` and FAIL if any matching
+        event arrived (timeout = test passes). For verifying that a
+        config (e.g. ``self_messages_only``) drops messages BEFORE the
+        agent ever sees them.
+
+    In all modes the runner:
+      1. Boots the agent via ``agent.boot(verbose=False)`` — same setup
+         ``agent.run()`` does in production (config watcher, MCP, skills,
+         usage reporter, integration manager, memory processing,
+         scheduler, restored-task triggers).
+      2. Clears runtime state so leftover tasks from prior runs don't
+         contaminate the LLM's view (does NOT wipe USER.md / MEMORY.md).
+      3. Waits for each integration in ``wait_for`` to report ``ready``.
+      4. Fires (or waits for) the chosen entry point.
+      5. Drains the trigger queue.
+
+    Returns ``{integration_id: status_dict}`` for every ``wait_for`` entry
+    so the test can pull ``owner_phone`` / ``owner_email`` / etc.
+    """
+    entry_modes = sum(
+        1 for x in (
+            user_message,
+            incoming_event,
+            wait_for_incoming or None,
+            expect_no_incoming or None,
+        ) if x is not None
+    )
+    if entry_modes != 1:
+        raise ValueError(
+            "run_scenario requires exactly one of user_message, "
+            "incoming_event, wait_for_incoming=True, or "
+            "expect_no_incoming=True"
+        )
+
+    # If we're going to wait for the bridge to deliver a message, the
+    # ``_handle_external_event`` spy MUST be installed BEFORE
+    # ``agent.boot()`` runs (which internally calls
+    # ``_initialize_external_libraries``). The integration manager
+    # captures a bound method reference to whatever ``on_message=`` it's
+    # handed at init time — replacing the attribute later doesn't update
+    # what the manager calls.
+    matched: asyncio.Event | None = None
+    captured: list[dict] = []
+    spy_kind: str | None = None  # "wait" or "silence"
+    orig_handler = agent._handle_external_event
+
+    if wait_for_incoming or expect_no_incoming:
+        matched = asyncio.Event()
+        spy_kind = "wait" if wait_for_incoming else "silence"
+
+        async def _external_event_spy(payload: dict) -> None:
+            if incoming_filter is None or incoming_filter(payload):
+                captured.append(payload)
+                if matched is not None:
+                    matched.set()
+            return await orig_handler(payload)
+
+        agent._handle_external_event = _external_event_spy
+
+    # Full production boot (mirrors what agent.run() does up to but not
+    # including the UI loop). Same boot as `app/main.py` performs, so the
+    # test environment matches production wiring exactly.
+    await agent.boot(browser_ui=False, verbose=False)
+
+    # Reset in-memory + persisted runtime state. Keeps USER.md / MEMORY.md.
+    await agent.triggers.clear()
+    agent.task_manager.reset()
+    agent.state_manager.reset()
+    agent.event_stream_manager.clear_all()
+    try:
+        from app.usage.session_storage import get_session_storage
+        get_session_storage().clear_all()
+    except Exception:
+        pass
+
+    async with record_llm_calls(agent), record_action_calls(agent):
+        # Poll each requested integration's session status until it's ready.
+        bridge_statuses: dict[str, dict] = {}
+        for pid in wait_for:
+            client = get_client(pid)
+            if client is None:
+                pytest.fail(f"integration {pid!r} client not registered")
+            deadline = time.time() + ready_timeout
+            while time.time() < deadline:
+                try:
+                    status = client.get_session_status()
+                    if asyncio.iscoroutine(status):
+                        status = await status
+                    if isinstance(status, dict) and (status.get("ready") or status.get("ok")):
+                        bridge_statuses[pid] = status
+                        break
+                except Exception:
+                    pass
+                await asyncio.sleep(1.0)
+            else:
+                pytest.fail(f"integration {pid!r} never became ready in {ready_timeout}s.")
+
+        # Production entry point — chat, synthesized external, or real
+        # bridge-driven external (wait for on-message to fire).
+        if user_message is not None:
+            payload: dict[str, Any] = {"text": user_message}
+            if platform:
+                payload["platform"] = platform
+            await agent._handle_chat_message(payload)
+        elif incoming_event is not None:
+            await agent._handle_external_event(incoming_event)
+        else:
+            # wait_for_incoming or expect_no_incoming. The spy was installed
+            # before agent.boot() above; now we just prompt + wait + interpret.
+            assert spy_kind in ("wait", "silence")
+            assert matched is not None
+            if incoming_prompt:
+                print(f"\n{incoming_prompt}\n", flush=True)
+            try:
+                try:
+                    await asyncio.wait_for(matched.wait(), timeout=incoming_timeout)
+                except asyncio.TimeoutError:
+                    if spy_kind == "wait":
+                        pytest.fail(
+                            f"No matching incoming event arrived within "
+                            f"{incoming_timeout}s. Did you send the message?"
+                        )
+                    # silence + timeout = expected silence, pass through
+                else:
+                    if spy_kind == "silence":
+                        p = captured[0]
+                        pytest.fail(
+                            f"Expected silence within {incoming_timeout}s but "
+                            f"a matching event reached the agent: "
+                            f"contact={p.get('contactName')!r}, "
+                            f"body={(p.get('messageBody') or '')[:120]!r}, "
+                            f"is_self_message={p.get('is_self_message')}"
+                        )
+            finally:
+                agent._handle_external_event = orig_handler
+
+        # Drain the trigger queue. Each react() may enqueue follow-up triggers
+        # (task lifecycle) — keep pulling until the queue stays empty past a
+        # short grace window.
+        for _ in range(max_iterations):
+            deadline = asyncio.get_event_loop().time() + 1.5
+            while not agent.triggers._heap and asyncio.get_event_loop().time() < deadline:
+                await asyncio.sleep(0.1)
+            if not agent.triggers._heap:
+                break
+            try:
+                trig = await asyncio.wait_for(agent.triggers.get(), timeout=per_iter_timeout)
+            except asyncio.TimeoutError:
+                break
+            await agent.react(trig)
+
+    return bridge_statuses
diff --git a/tests/e2e/_harness/trace.py b/tests/e2e/_harness/trace.py
new file mode 100644
index 00000000..0a5d06bb
--- /dev/null
+++ b/tests/e2e/_harness/trace.py
@@ -0,0 +1,265 @@
+"""Test-time logging: capture LLM calls, format the agent's event stream,
+and write per-test log files under ``tests/e2e/logs/``.
+
+The recording itself uses ``record_llm_calls`` — an async context manager
+that wraps both LLM methods (regular and session-cached). ``run_scenario``
+in [helpers.py](tests/e2e/_harness/helpers.py) enters it before driving
+the agent so every prompt + response gets stashed on
+``agent._test_llm_calls`` for ``save_trace_log`` to render afterwards.
+
+Public API
+----------
+
+- ``record_llm_calls(agent)`` — async context manager. Captures every
+  LLM call into ``agent._test_llm_calls`` for the duration of the block.
+- ``format_agent_trace(agent)`` — chronological merge of the main +
+  per-task event streams as a single human-readable string.
+- ``save_trace_log(agent, *, test_name=None, extra={})`` — write a
+  ``.log`` file containing the trace plus the full LLM transcript
+  (system prompt, user prompt, response per call). Returns the path.
+"""
+
+from __future__ import annotations
+
+import datetime
+import os
+import re
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from app.agent_base import AgentBase
+
+
+# Logs live at ``tests/e2e/logs/``. This file is in
+# ``tests/e2e/_harness/``, so go up one more level than the module.
+TEST_LOG_DIR = Path(__file__).resolve().parent.parent / "logs"
+
+
+@asynccontextmanager
+async def record_llm_calls(agent: AgentBase):
+    """Capture every LLM call the agent makes during the ``with`` block.
+
+    Wraps both ``generate_response_async`` (conversation-mode path) and
+    ``generate_response_with_session_async`` (task-mode path with session
+    caching). Each call is appended to ``agent._test_llm_calls`` as::
+
+        {"ts": float, "path": str, "system_prompt": str,
+         "user_prompt": str, "response": str}
+
+    Originals are restored on exit so the agent stays reusable.
+
+    This is the only seam through which we can see the actual prompts —
+    they're not written to the event stream or to disk anywhere else.
+    """
+    agent._test_llm_calls = []
+    orig_gen = agent.llm.generate_response_async
+    orig_session_gen = getattr(agent.llm, "generate_response_with_session_async", None)
+
+    async def _spy_gen(system_prompt=None, user_prompt=None, log_response=True):
+        resp = await orig_gen(
+            system_prompt=system_prompt, user_prompt=user_prompt,
+            log_response=log_response,
+        )
+        agent._test_llm_calls.append({
+            "ts": time.time(),
+            "path": "generate_response_async",
+            "system_prompt": system_prompt or "",
+            "user_prompt": user_prompt or "",
+            "response": str(resp),
+        })
+        return resp
+    agent.llm.generate_response_async = _spy_gen
+
+    if orig_session_gen is not None:
+        async def _spy_session(*args, **kwargs):
+            resp = await orig_session_gen(*args, **kwargs)
+            agent._test_llm_calls.append({
+                "ts": time.time(),
+                "path": "generate_response_with_session_async",
+                "system_prompt": kwargs.get("system_prompt_for_new_session", "") or "",
+                "user_prompt": kwargs.get("user_prompt", "") or "",
+                "response": str(resp),
+            })
+            return resp
+        agent.llm.generate_response_with_session_async = _spy_session
+
+    try:
+        yield
+    finally:
+        agent.llm.generate_response_async = orig_gen
+        if orig_session_gen is not None:
+            agent.llm.generate_response_with_session_async = orig_session_gen
+
+
+@asynccontextmanager
+async def record_action_calls(agent: AgentBase):
+    """Capture every action the agent invokes during the ``with`` block.
+
+    Wraps ``agent.action_manager.execute_action`` and records the action's
+    name on ``agent._test_actions_called`` (a list, in invocation order).
+
+    Why not just walk the event stream? Task-mode action_start events are
+    written to the TASK stream, not the main stream. When a task ends,
+    the task stream's events are flushed and the stream may be removed
+    from ``event_stream_manager._task_streams``, so reading after the
+    fact misses everything inside the task. This spy captures every
+    invocation as it happens, so it survives the task lifecycle.
+    """
+    agent._test_actions_called = []
+    orig = agent.action_manager.execute_action
+
+    async def _spy(action, *args, **kwargs):
+        try:
+            agent._test_actions_called.append(action.name)
+        except Exception:
+            pass
+        return await orig(action, *args, **kwargs)
+
+    agent.action_manager.execute_action = _spy
+    try:
+        yield
+    finally:
+        agent.action_manager.execute_action = orig
+
+
+def actions_called(agent: AgentBase) -> list[str]:
+    """List of action names the agent invoked during the scenario, in
+    invocation order. Populated by ``record_action_calls`` (entered by
+    ``run_scenario``)."""
+    return list(getattr(agent, "_test_actions_called", []) or [])
+
+
+def assert_action_called(
+    agent: AgentBase,
+    expected: str,
+    *,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Pass iff ``expected`` is among the actions the agent invoked.
+
+    Always writes a per-test log file first (so the trace is on disk for
+    inspection whether the assertion passes or fails), prints the log
+    path, then asserts. The failure message includes the full trace and
+    the list of actions actually called.
+    """
+    called = actions_called(agent)
+    log_extra = {"actions_called": called, "expecting": expected}
+    if extra:
+        log_extra.update(extra)
+    log_path = save_trace_log(agent, extra=log_extra)
+    print(f"\nagent trace: {log_path}")
+    assert expected in called, (
+        f"agent never called {expected!r}. Actions called: {called}. "
+        f"trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+
+
+def format_agent_trace(agent: AgentBase, *, limit_per_stream: int = 200) -> str:
+    """Chronological, human-readable timeline of everything the agent
+    recorded during the run.
+
+    Walks the in-memory main stream + per-task streams (``run_scenario``
+    clears these at the start of each test, so output is scoped to THIS
+    run — not polluted by prior runs the way the on-disk EVENT.md would
+    be).
+
+    Each line:  ``HH:MM:SS  [STREAM]  KIND  SEVERITY  message``
+    """
+    streams: list[tuple[str, Any]] = [("main", agent.event_stream_manager.get_main_stream())]
+    for tid, stream in agent.event_stream_manager._task_streams.items():
+        streams.append((f"task:{tid[:8]}", stream))
+
+    records: list[tuple[str, Any]] = []
+    for label, stream in streams:
+        for rec in (stream.tail_events or [])[-limit_per_stream:]:
+            records.append((label, rec))
+    records.sort(key=lambda lr: lr[1].ts)
+
+    lines: list[str] = []
+    for label, rec in records:
+        ev = rec.event
+        ts = ev.ts.strftime("%H:%M:%S")
+        msg = (ev.message or "").replace("\n", " | ")
+        if len(msg) > 240:
+            msg = msg[:237] + "..."
+        repeat = f" ×{rec.repeat_count}" if rec.repeat_count > 1 else ""
+        lines.append(f"{ts}  [{label:14}]  {ev.kind:18}  {ev.severity:5}  {msg}{repeat}")
+
+    return "\n".join(lines) if lines else "(no events recorded)"
+
+
+def _resolve_test_name(test_name: str | None) -> str:
+    """Pick a filename-safe test name, defaulting to pytest's current test."""
+    if not test_name:
+        current = os.environ.get("PYTEST_CURRENT_TEST", "")
+        # PYTEST_CURRENT_TEST looks like: "tests/e2e/file.py::test_func (call)"
+        if "::" in current:
+            test_name = current.split("::", 1)[1].split(" ", 1)[0]
+        else:
+            test_name = "trace"
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", test_name).strip("_") or "trace"
+
+
+def save_trace_log(
+    agent: AgentBase,
+    *,
+    test_name: str | None = None,
+    extra: dict[str, Any] | None = None,
+) -> Path:
+    """Write a per-test log file containing the agent's event trace +
+    every LLM call captured during the run.
+
+    File path:
+        ``tests/e2e/logs/<test_name>_<UTC YYYYMMDD_HHMMSS>.log``
+
+    Test name auto-derived from ``PYTEST_CURRENT_TEST`` if not given.
+    ``extra`` becomes "# KEY: value" header lines.
+
+    Returns the written path so tests can print it or attach to a
+    failure message.
+    """
+    TEST_LOG_DIR.mkdir(parents=True, exist_ok=True)
+    name = _resolve_test_name(test_name)
+    now = datetime.datetime.now(datetime.timezone.utc)
+    stamp = now.strftime("%Y%m%d_%H%M%S")
+    path = TEST_LOG_DIR / f"{name}_{stamp}.log"
+
+    llm_calls = getattr(agent, "_test_llm_calls", []) or []
+
+    parts: list[str] = []
+    parts.append(f"# test: {name}")
+    parts.append(f"# written: {now.isoformat()}")
+    parts.append(f"# llm_calls: {len(llm_calls)}")
+    if extra:
+        for k, v in extra.items():
+            parts.append(f"# {k}: {v}")
+    parts.append("")
+    parts.append("=" * 78)
+    parts.append("AGENT TRACE (event streams; chronological)")
+    parts.append("=" * 78)
+    parts.append(format_agent_trace(agent))
+
+    if llm_calls:
+        parts.append("")
+        parts.append("=" * 78)
+        parts.append(f"LLM TRANSCRIPT ({len(llm_calls)} call{'s' if len(llm_calls) != 1 else ''})")
+        parts.append("=" * 78)
+        for i, c in enumerate(llm_calls, 1):
+            ts = datetime.datetime.fromtimestamp(c["ts"], datetime.timezone.utc).strftime("%H:%M:%S")
+            parts.append("")
+            parts.append(f"--- call {i}/{len(llm_calls)} @ {ts}  via {c['path']} ---")
+            parts.append("")
+            parts.append(f"SYSTEM PROMPT ({len(c['system_prompt'])} chars):")
+            parts.append(c["system_prompt"] or "(empty)")
+            parts.append("")
+            parts.append(f"USER PROMPT ({len(c['user_prompt'])} chars):")
+            parts.append(c["user_prompt"] or "(empty)")
+            parts.append("")
+            parts.append(f"RESPONSE ({len(c['response'])} chars):")
+            parts.append(c["response"] or "(empty)")
+
+    path.write_text("\n".join(parts), encoding="utf-8")
+    return path
diff --git a/tests/e2e/_integrations/__init__.py b/tests/e2e/_integrations/__init__.py
new file mode 100644
index 00000000..c98b65a8
--- /dev/null
+++ b/tests/e2e/_integrations/__init__.py
@@ -0,0 +1,18 @@
+"""Per-integration verification helpers for LIVE end-to-end tests.
+
+Each integration module in here owns the knowledge of:
+  - the integration's client + how to extract the owner's identifier
+    (e.g. ``owner_phone`` for whatsapp_web, ``emailAddress`` for gmail).
+  - how to query "did a recent outgoing message land in my own chat?"
+    using the integration's native methods (``get_chat_messages`` for
+    whatsapp, ``users.messages.list`` for gmail, etc.).
+
+The generic infrastructure (``build_agent``, ``run_scenario``) lives in
+[..._live_helpers.py](tests/e2e/_live_helpers.py); it stays integration-
+agnostic. Tests import generic infra from there and integration-specific
+verification from this package.
+
+Adding support for a new integration is a single new module here exposing
+``recent_messages_in_self_chat(*, since_ts, contains=None) -> list[dict]``
+(or the equivalent verb for that integration's primary surface).
+"""
diff --git a/tests/e2e/_integrations/gmail.py b/tests/e2e/_integrations/gmail.py
new file mode 100644
index 00000000..1d75f356
--- /dev/null
+++ b/tests/e2e/_integrations/gmail.py
@@ -0,0 +1,114 @@
+"""Gmail-specific verification helpers for live e2e tests.
+
+All the Gmail API specifics live here:
+  - the owner identifier is ``cred.email`` (stored on ``GoogleCredential``).
+  - sent emails live in the ``SENT`` label and are queried via Gmail's
+    search syntax (``in:sent``, ``after:`` for time bounds, free-text for
+    body matches).
+  - the underlying ``send_email`` / ``list_emails`` / etc. on the client
+    are sync (REST), unlike WhatsApp's async bridge methods.
+
+Tests just call ``recent_sent_emails(contains=...)`` and assert on the
+returned list — no GmailAPI plumbing leaks into the test body.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from craftos_integrations import get_client
+from craftos_integrations.helpers import request as http_request
+from craftos_integrations.integrations.gmail import GMAIL_API_BASE
+
+
+INTEGRATION_ID = "gmail"
+
+
+def owner_email() -> str:
+    """The Gmail address the user is logged in as. Empty string if the
+    client isn't registered or has no credentials.
+    """
+    client = get_client(INTEGRATION_ID)
+    if client is None:
+        return ""
+    try:
+        cred = client._load()
+    except Exception:
+        return ""
+    return getattr(cred, "email", "") or ""
+
+
+async def recent_sent_emails(
+    *,
+    contains: str | None = None,
+    since_ts: float | None = None,
+    limit: int = 10,
+) -> list[dict]:
+    """Return emails the user's Gmail account sent recently.
+
+    Uses Gmail's search syntax (``in:sent`` + free-text + ``after:``)
+    so the filter happens server-side — no need to fetch + post-filter.
+
+    Args:
+        contains: optional case-insensitive substring matched against the
+            message body OR subject (Gmail does whole-word fuzzy by
+            default; a quoted phrase is treated as an exact substring).
+        since_ts: optional unix timestamp lower bound. Gmail's ``after:``
+            accepts unix seconds.
+        limit: how many results to fetch.
+
+    Returns a list of dicts with at least ``id``, ``snippet``, plus
+    headers ``From`` / ``To`` / ``Subject`` / ``Date`` when present.
+    Empty list = no match.
+    """
+    client = get_client(INTEGRATION_ID)
+    if client is None:
+        return []
+
+    # We avoid Gmail's ``after:`` filter — it's quirky around unix
+    # timestamps and the agent's own sentinel is already unique enough to
+    # bound the match. If callers want a time bound for safety they can
+    # filter ``timestamp`` on the returned dicts themselves.
+    query_parts = ["in:sent"]
+    if contains:
+        # Quote so Gmail treats it as a phrase rather than tokenizing.
+        query_parts.append(f'"{contains}"')
+    q = " ".join(query_parts)
+    _ = since_ts  # kept for API compatibility; unused for now
+
+    # Gmail's search returns IDs only; we fetch each one for snippet +
+    # headers. This is the same shape ``client.read_top_emails`` produces
+    # but scoped to Sent + filtered by query.
+    def _list_sync():
+        return http_request(
+            "GET", f"{GMAIL_API_BASE}/users/me/messages",
+            headers=client._auth_header(),
+            params={"q": q, "maxResults": limit},
+            expected=(200,),
+            transform=lambda d: d.get("messages", []),
+        )
+
+    envelope = await asyncio.to_thread(_list_sync)
+    # ``request`` wraps every response in ``{"ok": True, "result": ...}``
+    # on success or ``{"error": ..., "details": ...}`` on failure. Unwrap.
+    if not isinstance(envelope, dict) or "error" in envelope:
+        return []
+    listing = envelope.get("result")
+    if not isinstance(listing, list):
+        return []
+
+    def _fetch_one(mid: str):
+        return client.get_email(message_id=mid, full_body=False)
+
+    results: list[dict] = []
+    for entry in listing:
+        mid = entry.get("id")
+        if not mid:
+            continue
+        detail_envelope = await asyncio.to_thread(_fetch_one, mid)
+        if not isinstance(detail_envelope, dict) or "error" in detail_envelope:
+            continue
+        detail = detail_envelope.get("result", detail_envelope)
+        if isinstance(detail, dict) and detail.get("id"):
+            results.append(detail)
+    return results
diff --git a/tests/e2e/_integrations/whatsapp.py b/tests/e2e/_integrations/whatsapp.py
new file mode 100644
index 00000000..a9faf642
--- /dev/null
+++ b/tests/e2e/_integrations/whatsapp.py
@@ -0,0 +1,104 @@
+"""WhatsApp Web verification helpers for live e2e tests.
+
+All the wwebjs-bridge-specific knowledge lives here:
+  - the owner's identifier is ``owner_phone`` (bare E.164 without ``+``).
+  - the self-chat id is the owner's phone (the bridge appends ``@c.us``).
+  - chat history comes back from ``get_chat_messages`` as a list with
+    ``{id, body, from, from_me, timestamp, type, has_media}`` per
+    [bridge.js:478-486](craftos_integrations/integrations/whatsapp_web/bridge.js#L478).
+
+Tests just call ``recent_messages_in_self_chat(since_ts=...)`` and assert
+on the returned list — no platform plumbing leaks into the test body.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+
+from craftos_integrations import get_client
+from craftos_integrations.credentials_store import (
+    has_config,
+    load_config,
+    remove_config,
+    save_config,
+)
+from craftos_integrations.integrations.whatsapp_web import WhatsAppWebConfig
+
+
+INTEGRATION_ID = "whatsapp_web"
+_CONFIG_FILE = "whatsapp_web_config.json"
+
+
+@contextmanager
+def self_messages_only(enabled: bool):
+    """Temporarily set the WhatsApp Web ``self_messages_only`` config flag,
+    snapshotting + restoring the prior value on exit.
+
+    When ``True``, the integration drops every incoming message except
+    self-chat ones BEFORE the on-message callback fires — third-party
+    messages never reach the agent at all (see
+    ``WhatsAppWebClient._handle_incoming_message`` in
+    [whatsapp_web/__init__.py](craftos_integrations/integrations/whatsapp_web/__init__.py)).
+
+    Usage in tests::
+
+        with whatsapp.self_messages_only(True):
+            asyncio.run(_run_scenario(...))
+    """
+    original = load_config(_CONFIG_FILE, WhatsAppWebConfig)
+    existed_before = has_config(_CONFIG_FILE)
+    save_config(_CONFIG_FILE, WhatsAppWebConfig(self_messages_only=enabled))
+    try:
+        yield
+    finally:
+        if existed_before and original is not None:
+            save_config(_CONFIG_FILE, original)
+        else:
+            remove_config(_CONFIG_FILE)
+
+
+async def recent_messages_in_self_chat(
+    *,
+    since_ts: float,
+    contains: str | None = None,
+    limit: int = 20,
+) -> list[dict]:
+    """Return outgoing messages in the owner's own whatsapp chat that
+    landed at or after ``since_ts``.
+
+    Args:
+        since_ts: unix timestamp (seconds). Only messages with
+            ``timestamp >= since_ts`` are returned. Pass ``time.time()``
+            recorded BEFORE the agent runs (subtract a couple of seconds
+            for clock-skew between Python and whatsapp-web.js).
+        contains: optional case-insensitive substring filter on the
+            message body.
+        limit: how many recent messages to fetch from the bridge.
+
+    Returns ``[]`` if the bridge isn't ready, the session has no owner
+    info yet, or nothing in the window matches.
+    """
+    client = get_client(INTEGRATION_ID)
+    if client is None:
+        return []
+
+    status = client.get_session_status()
+    if asyncio.iscoroutine(status):
+        status = await status
+    owner_phone = (status or {}).get("owner_phone", "")
+    if not owner_phone:
+        return []
+
+    response = client.get_chat_messages(phone_number=owner_phone, limit=limit)
+    if asyncio.iscoroutine(response):
+        response = await response
+    messages = response.get("messages", []) if isinstance(response, dict) else []
+
+    needle = contains.lower() if contains else None
+    return [
+        m for m in messages
+        if m.get("from_me", False)
+        and (m.get("timestamp") or 0) >= since_ts
+        and (not needle or needle in (m.get("body") or "").lower())
+    ]
diff --git a/tests/e2e/test_live_gmail.py b/tests/e2e/test_live_gmail.py
new file mode 100644
index 00000000..e9b8159b
--- /dev/null
+++ b/tests/e2e/test_live_gmail.py
@@ -0,0 +1,259 @@
+"""LIVE end-to-end scenarios for Gmail.
+
+Same black-box shape as the whatsapp suite: build the real agent, send
+it a chat message via the production entry point, let it do its full
+lifecycle, then ask Gmail itself "is there a matching email in my Sent
+folder?" or assert which read-action the agent invoked.
+
+Generic infrastructure lives in [_harness/](tests/e2e/_harness/);
+Gmail-specific verification lives in
+[_integrations/gmail.py](tests/e2e/_integrations/gmail.py).
+
+**Opt-in.** Default ``pytest`` runs skip these. Run with::
+
+    python -m pytest tests/e2e/test_live_gmail.py -v -m live -s
+
+They spend LLM tokens and send REAL emails to your own inbox.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+
+from tests.e2e._harness import (
+    assert_action_called,
+    build_agent,
+    format_agent_trace,
+    run_scenario,
+    save_trace_log,
+)
+from tests.e2e._integrations import gmail
+
+
+pytestmark = pytest.mark.live
+
+
+# ---------------------------------------------------------------------------
+# Send-side scenarios — verified by querying Gmail's Sent folder for an
+# outgoing message written during the test window.
+# ---------------------------------------------------------------------------
+
+
+def test_live_gmail_send_to_me():
+    """Agent emails the user themselves. After the lifecycle finishes,
+    we ask Gmail directly whether a sent email matches the body sentinel.
+    Passes regardless of which path the agent took (``send_gmail`` vs
+    ``send_google_workspace_email``).
+
+    The user's own email is threaded into the prompt explicitly (via
+    ``gmail.owner_email()``) so the test doesn't depend on the agent
+    inferring "me" from the integration_essentials block — Gemini
+    sometimes asks for clarification even when the essentials forbid it.
+
+    Manual verification: a 'gmail e2e test ping' message arrives in your
+    inbox.
+    """
+    agent = build_agent(require=["gmail"])
+    test_start_ts = time.time() - 5
+    sentinel = f"gmail e2e test {int(time.time())}"
+    to_addr = gmail.owner_email()
+    assert to_addr, "couldn't determine the user's gmail address from credentials"
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message=(
+                f"send a Gmail email (use the send_gmail action, not outlook) "
+                f"to {to_addr} with subject 'craftbot e2e' and body '{sentinel}'."
+            ),
+            max_iterations=30,
+        )
+        # Gmail's API has a small propagation delay between send and
+        # appearing in the Sent folder via search.
+        # Gmail can take 10–20s to index a new sent message for search.
+        await asyncio.sleep(15.0)
+        return await gmail.recent_sent_emails(
+            contains=sentinel, since_ts=test_start_ts,
+        )
+
+    recent = asyncio.run(_run())
+    log_path = save_trace_log(
+        agent,
+        extra={"sentinel": sentinel, "matched_sent_emails": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no sent email containing the sentinel arrived in your Gmail "
+        f"Sent folder. sentinel={sentinel!r}. trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+
+
+def test_live_gmail_threads_user_content_through():
+    """Quoted phrase verbatim — verifies the agent doesn't paraphrase
+    when threading body content. Unique sentinel per run.
+    """
+    agent = build_agent(require=["gmail"])
+    test_start_ts = time.time() - 5
+    sentinel = f"craftbot-gmail-{int(time.time())}"
+    to_addr = gmail.owner_email()
+    assert to_addr, "couldn't determine the user's gmail address from credentials"
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message=(
+                f"send a Gmail email (use the send_gmail action) to {to_addr} "
+                f"with this exact body text: '{sentinel}'. "
+                f"subject: 'craftbot e2e threading'."
+            ),
+            max_iterations=30,
+        )
+        # Gmail can take 10–20s to index a new sent message for search.
+        await asyncio.sleep(15.0)
+        return await gmail.recent_sent_emails(
+            contains=sentinel, since_ts=test_start_ts,
+        )
+
+    recent = asyncio.run(_run())
+    log_path = save_trace_log(
+        agent,
+        extra={"sentinel": sentinel, "matched_sent_emails": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no sent email containing the sentinel arrived. The agent may "
+        f"have paraphrased the body instead of threading verbatim. "
+        f"sentinel={sentinel!r}. trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+
+
+def test_live_gmail_sends_unicode_body():
+    """Emoji + non-Latin scripts must survive the MIME-encoded send path
+    in [gmail.py](craftos_integrations/integrations/gmail.py) and round-
+    trip back through Gmail's search.
+    """
+    agent = build_agent(require=["gmail"])
+    test_start_ts = time.time() - 5
+    rocket = "🚀"
+    body = f"héllo 你好 {rocket} {int(time.time())}"
+    to_addr = gmail.owner_email()
+    assert to_addr, "couldn't determine the user's gmail address from credentials"
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message=(
+                f"send a Gmail email (use the send_gmail action) to {to_addr} "
+                f"with this exact body text: '{body}'. "
+                f"subject: 'craftbot e2e unicode'."
+            ),
+            max_iterations=30,
+        )
+        # Gmail can take 10–20s to index a new sent message for search.
+        await asyncio.sleep(15.0)
+        # Search for the rocket — if Gmail or the MIME encoder mangled
+        # it to '?' or a numeric reference, this finds nothing.
+        return await gmail.recent_sent_emails(
+            contains=rocket, since_ts=test_start_ts,
+        )
+
+    recent = asyncio.run(_run())
+    log_path = save_trace_log(
+        agent,
+        extra={"body_sentinel": body, "matched_with_rocket": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no sent email containing the rocket emoji landed in your Sent "
+        f"folder. The MIME encoder or Gmail may be mangling unicode. "
+        f"trace: {log_path}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Read-side scenarios — verified by which action the agent invoked.
+# No outgoing emails expected.
+# ---------------------------------------------------------------------------
+
+
+def test_live_gmail_lists_unread_emails():
+    """Asking for unread emails should fire ``list_gmail`` (or its
+    google_workspace alias). We don't assert the count of unread — only
+    that the agent reached for a read action instead of asking the user.
+    """
+    agent = build_agent(require=["gmail"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message=(
+                "use the list_gmail action to fetch my unread Gmail emails. "
+                "list the senders and subjects. don't ask me anything — "
+                "use Gmail (not outlook) and act now."
+            ),
+            max_iterations=30,
+        )
+
+    asyncio.run(_run())
+    # Either action_set is acceptable — they both pull from the same
+    # Gmail API. Assert at least one fired.
+    from tests.e2e._harness import actions_called
+    called = actions_called(agent)
+    log_path = save_trace_log(
+        agent, extra={"actions_called": called, "expecting_any_of": [
+            "list_gmail", "read_top_emails", "read_recent_google_workspace_emails",
+        ]},
+    )
+    print(f"\nagent trace: {log_path}")
+    acceptable = {
+        "list_gmail", "read_top_emails", "read_recent_google_workspace_emails",
+    }
+    assert acceptable.intersection(called), (
+        f"agent didn't call any gmail read action. Called: {called}. "
+        f"trace: {log_path}\n\n" + format_agent_trace(agent)
+    )
+
+
+def test_live_gmail_reads_top_emails_with_details():
+    """Asking to summarise recent emails should fire ``read_top_emails``
+    (or the equivalent google_workspace action) — it's the only Gmail
+    action that returns body content in one call.
+    """
+    agent = build_agent(require=["gmail"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message=(
+                "summarise the last 3 emails in my Gmail inbox using the "
+                "read_top_emails action. include who sent them and what each "
+                "one is about. don't ask me anything — use Gmail (not "
+                "outlook) and act now."
+            ),
+            max_iterations=30,
+        )
+
+    asyncio.run(_run())
+    from tests.e2e._harness import actions_called
+    called = actions_called(agent)
+    log_path = save_trace_log(
+        agent, extra={"actions_called": called, "expecting_any_of": [
+            "read_top_emails", "read_recent_google_workspace_emails",
+        ]},
+    )
+    print(f"\nagent trace: {log_path}")
+    acceptable = {
+        "read_top_emails", "read_recent_google_workspace_emails",
+    }
+    assert acceptable.intersection(called), (
+        f"agent didn't call a read-with-body gmail action. Called: {called}. "
+        f"trace: {log_path}\n\n" + format_agent_trace(agent)
+    )
diff --git a/tests/e2e/test_live_whatsapp.py b/tests/e2e/test_live_whatsapp.py
new file mode 100644
index 00000000..64100148
--- /dev/null
+++ b/tests/e2e/test_live_whatsapp.py
@@ -0,0 +1,442 @@
+"""LIVE end-to-end scenarios for WhatsApp.
+
+One file per integration so test files stay scoped and easy to grow.
+Generic infrastructure lives in [_harness/](tests/e2e/_harness/);
+WhatsApp-specific verification lives in
+[_integrations/whatsapp.py](tests/e2e/_integrations/whatsapp.py).
+
+Each test:
+
+1. Builds the real agent (skips if whatsapp_web isn't connected).
+2. Sends a chat message through the same entry point the CraftBot UI uses.
+3. After the agent's full lifecycle finishes, verifies the outcome
+   black-box:
+     - send tests: ``whatsapp.recent_messages_in_self_chat(...)``
+     - read tests: ``assert_action_called(agent, <expected action>)``
+4. Writes a per-test log file under ``tests/e2e/logs/`` with the agent
+   trace + full LLM transcript.
+
+**Opt-in.** Default ``pytest`` runs skip these. Run with::
+
+    python -m pytest tests/e2e/test_live_whatsapp.py -v -m live -s
+
+They spend LLM tokens and send REAL WhatsApp messages to the linked
+account's own number.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+
+from tests.e2e._harness import (
+    actions_called,
+    assert_action_called,
+    build_agent,
+    format_agent_trace,
+    run_scenario,
+    save_trace_log,
+)
+from tests.e2e._integrations import whatsapp
+
+
+pytestmark = pytest.mark.live
+
+
+# ---------------------------------------------------------------------------
+# Send-side scenarios — verified by querying the wwebjs chat history for an
+# outgoing message in the owner's own chat, written during the test window.
+# ---------------------------------------------------------------------------
+
+
+def test_live_whatsapp_send_ping_to_me():
+    """User asks the agent to whatsapp themselves. After the agent settles,
+    we ask whatsapp directly: 'do you have a recent outgoing message from
+    me to me?'. Passes regardless of which code path the agent took.
+
+    Manual verification: a message arrives on your phone.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    # Round down a couple of seconds for clock-skew safety between Python's
+    # time.time() and whatsapp-web.js's message timestamps.
+    test_start_ts = time.time() - 2
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message="send me a whatsapp message saying 'ping from test'",
+            wait_for=["whatsapp_web"],
+        )
+        # Bridge flush before query.
+        await asyncio.sleep(2.0)
+        return await whatsapp.recent_messages_in_self_chat(since_ts=test_start_ts)
+
+    recent = asyncio.run(_run())
+    log_path = save_trace_log(
+        agent,
+        extra={"recent_messages_in_self_chat": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no outgoing whatsapp message landed in your self-chat after "
+        f"the test window. trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+
+
+def test_live_whatsapp_threads_user_content_through():
+    """Verifies the agent threads a quoted phrase verbatim instead of
+    paraphrasing. The sentinel is unique per run so re-runs don't
+    false-positive on prior runs' messages.
+    """
+    sentinel = f"craftbot-e2e-{int(time.time())}"
+    agent = build_agent(require=["whatsapp_web"])
+    test_start_ts = time.time() - 2
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message=f"send me a whatsapp with this exact text: '{sentinel}'",
+            wait_for=["whatsapp_web"],
+        )
+        await asyncio.sleep(2.0)
+        return await whatsapp.recent_messages_in_self_chat(
+            since_ts=test_start_ts, contains=sentinel,
+        )
+
+    recent = asyncio.run(_run())
+    log_path = save_trace_log(
+        agent,
+        extra={"sentinel": sentinel, "matched_messages": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no whatsapp message containing the sentinel arrived. The agent "
+        f"may have paraphrased instead of threading the exact phrase. "
+        f"sentinel={sentinel!r}. trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+
+
+def test_live_whatsapp_sends_unicode_body():
+    """Emoji + non-Latin scripts must survive Python → wwebjs subprocess
+    JSON → WhatsApp's API → the bridge's chat history readback. Catches
+    encoding bugs anywhere in that chain.
+    """
+    sentinel = f"héllo 你好 🚀 {int(time.time())}"
+    rocket = "🚀"
+    agent = build_agent(require=["whatsapp_web"])
+    test_start_ts = time.time() - 2
+
+    async def _run() -> list[dict]:
+        await run_scenario(
+            agent,
+            user_message=f"send me a whatsapp with this exact text: '{sentinel}'",
+            wait_for=["whatsapp_web"],
+        )
+        await asyncio.sleep(2.0)
+        return await whatsapp.recent_messages_in_self_chat(
+            since_ts=test_start_ts, contains=rocket,
+        )
+
+    recent = asyncio.run(_run())
+    # Log file is UTF-8; keep console print pure ASCII for Windows cp1252.
+    log_path = save_trace_log(
+        agent,
+        extra={"sentinel": sentinel, "matched_with_rocket": len(recent)},
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert recent, (
+        f"no whatsapp message containing the rocket emoji arrived. The "
+        f"wwebjs bridge may be mangling unicode. trace: {log_path}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Read-side scenarios — verified by asserting on which action(s) the agent
+# invoked, via the ``execute_action`` spy recorded in
+# ``agent._test_actions_called``. No outgoing messages expected.
+# ---------------------------------------------------------------------------
+
+
+def test_live_whatsapp_query_session_status_for_my_number():
+    """Asking for one's own whatsapp number should make the agent look it
+    up via ``get_whatsapp_web_session_status`` (per the integration's
+    ## Essentials block — "Never ask the user for it"). Regression check
+    that the essentials reach task-mode prompts.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message=(
+                "what is my own whatsapp phone number? look it up — don't ask me."
+            ),
+            wait_for=["whatsapp_web"],
+        )
+
+    asyncio.run(_run())
+    assert_action_called(agent, "get_whatsapp_web_session_status")
+
+
+def test_live_whatsapp_checks_unread_chats():
+    """Asking about unread whatsapp messages should fire
+    ``get_whatsapp_unread_chats``. Result (0 vs N) doesn't matter; only
+    that the agent reached for the right action.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message="do i have any unread whatsapp messages? list them.",
+            wait_for=["whatsapp_web"],
+        )
+
+    asyncio.run(_run())
+    assert_action_called(agent, "get_whatsapp_unread_chats")
+
+
+def test_live_whatsapp_searches_contact_by_name():
+    """Asking the agent to find a contact by name should fire
+    ``search_whatsapp_contact``. We don't assert the search FOUND the
+    contact — only that the agent reasoned to search instead of asking
+    the user for a phone number.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message=(
+                "search my whatsapp contacts for someone named 'craftbot test'. "
+                "tell me what you find."
+            ),
+            wait_for=["whatsapp_web"],
+        )
+
+    asyncio.run(_run())
+    assert_action_called(agent, "search_whatsapp_contact")
+
+
+# ---------------------------------------------------------------------------
+# Incoming-message scenarios — feed the agent a message that LOOKS like it
+# came from the wwebjs bridge's on-message callback, via the same
+# ``_handle_external_event`` entry the integration manager uses in
+# production. We do NOT actually receive a message from outside — we
+# synthesize the payload and inject it.
+# ---------------------------------------------------------------------------
+
+
+def test_live_whatsapp_self_message_from_phone_triggers_reply():
+    """REAL bridge flow: you send a WhatsApp from your phone to yourself.
+    The wwebjs bridge picks it up and emits an on-message event with
+    ``is_self_message=True``. The agent wraps it as a user instruction
+    (per [agent_base.py:2358](app/agent_base.py#L2358)) and replies.
+
+    The bridge SUPPRESSES its own bridge-initiated sends from the
+    on-message callback (see ownSentIds tracking in bridge.js) — so we
+    can't automate this. You have to send from your phone within 30s.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            wait_for_incoming=True,
+            wait_for=["whatsapp_web"],
+            incoming_prompt=(
+                ">>> SEND A WHATSAPP TO YOURSELF FROM YOUR PHONE NOW (30s).\n"
+                ">>> Any message body works — the agent will reply to it."
+            ),
+            incoming_filter=lambda p: bool(p.get("is_self_message")),
+            incoming_timeout=30.0,
+        )
+
+    # Explicit "default" config: self_messages_only=False. The user's
+    # production config may have this set to True (which is fine for daily
+    # use — it'd just drop third-party messages), so we force False here
+    # so the test is independent of host state. The context manager
+    # snapshots the current value and restores it on exit.
+    with whatsapp.self_messages_only(False):
+        asyncio.run(_run())
+    assert_action_called(agent, "send_whatsapp_web_text_message")
+
+
+def test_live_whatsapp_third_party_message_is_notification_only():
+    """REAL bridge flow: someone else WhatsApps you. The bridge picks it
+    up, on-message fires with ``is_self_message=False``, and per the
+    hardcoded routing rule at [agent_base.py:2213-2217](app/agent_base.py#L2213)
+    the chat handler short-circuits to ``_post_third_party_notification``
+    BEFORE any LLM call. The agent must NOT reply on the sender's
+    behalf.
+
+    Verifications:
+      - no LLM calls were made (third-party branch short-circuited),
+      - no actions were invoked (no react() ran),
+      - no outgoing whatsapp message landed in the owner's chat.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+    test_start_ts = time.time() - 2
+
+    async def _run():
+        await run_scenario(
+            agent,
+            wait_for_incoming=True,
+            wait_for=["whatsapp_web"],
+            incoming_prompt=(
+                ">>> HAVE SOMEONE ELSE SEND YOU A WHATSAPP NOW (30s).\n"
+                ">>> Must be from a different account/contact. Any body works."
+            ),
+            incoming_filter=lambda p: p.get("is_self_message") is False,
+            incoming_timeout=30.0,
+        )
+        # Give the bridge a moment in case anything (wrongly) tried to send.
+        await asyncio.sleep(2.0)
+        return await whatsapp.recent_messages_in_self_chat(since_ts=test_start_ts)
+
+    # Force self_messages_only=False so third-party messages reach the
+    # agent. Without this, the user's production config (which may have
+    # self_messages_only=True) would drop the message at the integration
+    # layer and the test would time out waiting forever.
+    with whatsapp.self_messages_only(False):
+        sent_to_self = asyncio.run(_run())
+    invoked = actions_called(agent)
+    llm_calls = getattr(agent, "_test_llm_calls", []) or []
+
+    log_path = save_trace_log(
+        agent,
+        extra={
+            "llm_calls": len(llm_calls),
+            "actions_called": invoked,
+            "self_chat_sends_during_test": len(sent_to_self),
+        },
+    )
+    print(f"\nagent trace: {log_path}")
+
+    assert not llm_calls, (
+        f"agent invoked the LLM ({len(llm_calls)} call(s)) for a third-"
+        f"party whatsapp message. The notification-only branch should have "
+        f"short-circuited. trace: {log_path}\n\n"
+        + format_agent_trace(agent)
+    )
+    assert not invoked, (
+        f"agent invoked actions {invoked} for a third-party whatsapp "
+        f"message. Should be empty. trace: {log_path}"
+    )
+    assert not sent_to_self, (
+        f"agent sent {len(sent_to_self)} whatsapp message(s) in response "
+        f"to a third-party message. The notification-only rule was "
+        f"violated. trace: {log_path}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Incoming-message scenarios with ``self_messages_only=True`` config —
+# the integration-level filter at
+# [whatsapp_web/__init__.py:_handle_incoming_message](craftos_integrations/integrations/whatsapp_web/__init__.py)
+# drops non-self messages BEFORE the on-message callback. Self-messages
+# go through ``_handle_sent_message`` and aren't affected.
+# ---------------------------------------------------------------------------
+
+
+def test_live_whatsapp_self_only_config_still_processes_self_message():
+    """With ``self_messages_only=True`` the integration must still forward
+    self-messages to the agent — only third-party messages are dropped.
+    You send a whatsapp to yourself from your phone within 30s; agent
+    should still reply via ``send_whatsapp_web_text_message``.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            wait_for_incoming=True,
+            wait_for=["whatsapp_web"],
+            incoming_prompt=(
+                ">>> [self_messages_only=True] SEND A WHATSAPP TO YOURSELF "
+                "FROM YOUR PHONE NOW (30s). Agent should still reply."
+            ),
+            incoming_filter=lambda p: bool(p.get("is_self_message")),
+            incoming_timeout=30.0,
+        )
+
+    with whatsapp.self_messages_only(True):
+        asyncio.run(_run())
+
+    assert_action_called(agent, "send_whatsapp_web_text_message")
+
+
+def test_live_whatsapp_self_only_config_drops_third_party():
+    """With ``self_messages_only=True`` a third-party message must be
+    DROPPED at the integration layer — ``_handle_external_event`` is
+    never invoked, so the agent doesn't even see it. Differs from the
+    notification-only third-party test (which verifies the agent's
+    ROUTING when the event does reach it).
+
+    You ask someone else to whatsapp you within 30s. Test passes by
+    timing out (no matching event ever reaches the agent).
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            expect_no_incoming=True,
+            wait_for=["whatsapp_web"],
+            incoming_prompt=(
+                ">>> [self_messages_only=True] HAVE SOMEONE ELSE WHATSAPP "
+                "YOU IN THE NEXT 30s. The integration must DROP it before "
+                "the agent sees it. Test passes by timing out silently."
+            ),
+            # We only care about third-party arrivals reaching the agent;
+            # ignore any self-messages that might also arrive in the window.
+            incoming_filter=lambda p: p.get("is_self_message") is False,
+            incoming_timeout=30.0,
+        )
+
+    with whatsapp.self_messages_only(True):
+        asyncio.run(_run())
+
+    # Belt-and-suspenders: no actions, no LLM, no outgoing message.
+    llm_calls = getattr(agent, "_test_llm_calls", []) or []
+    invoked = actions_called(agent)
+    log_path = save_trace_log(
+        agent,
+        extra={"llm_calls": len(llm_calls), "actions_called": invoked},
+    )
+    print(f"\nagent trace: {log_path}")
+    assert not llm_calls and not invoked, (
+        f"agent reacted to a message that should have been dropped at the "
+        f"integration layer. llm_calls={len(llm_calls)}, actions={invoked}. "
+        f"trace: {log_path}"
+    )
+
+
+def test_live_whatsapp_reads_self_chat_history():
+    """Asking for the last whatsapp message in self-chat should fire
+    ``get_whatsapp_chat_history``. The agent will likely call
+    ``get_whatsapp_web_session_status`` first to find the owner's phone,
+    then ``get_whatsapp_chat_history`` against it.
+    """
+    agent = build_agent(require=["whatsapp_web"])
+
+    async def _run():
+        await run_scenario(
+            agent,
+            user_message=(
+                "look up the last whatsapp message i sent to myself. "
+                "use my own number for the chat."
+            ),
+            wait_for=["whatsapp_web"],
+        )
+
+    asyncio.run(_run())
+    assert_action_called(agent, "get_whatsapp_chat_history")
diff --git a/tests/e2e/test_smoke.py b/tests/e2e/test_smoke.py
new file mode 100644
index 00000000..07a95dcd
--- /dev/null
+++ b/tests/e2e/test_smoke.py
@@ -0,0 +1,115 @@
+"""Level-1 smoke tests: action registry + simulated handlers.
+
+Cheapest layer of the testing pyramid. Verifies:
+1. The action registry loads at all.
+2. Actions the agent's routing depends on exist.
+3. An action's test_payload + simulated_mode flow runs end-to-end.
+
+These tests do NOT boot the full agent (no LLM, no DB, no integrations).
+See test_action_router.py for level-2 tests that mock the LLM and exercise
+ActionRouter routing decisions.
+"""
+
+import asyncio
+import inspect
+import platform
+
+import pytest
+
+from agent_core import load_actions_from_directories, registry_instance
+
+
+# Action handlers whose test_payload + simulated_mode flow is currently
+# broken — the handler doesn't honor simulated_mode before hitting the real
+# filesystem / interface. Each one is a separate action-side fix; skip here
+# so the registry-wide smoke loop stays green.
+#   find_files: hardcoded C:\Users\user\Documents in test_payload
+#   send_message_with_attachment: validates file paths before simulated branch
+KNOWN_BROKEN_TEST_PAYLOADS = {
+    "find_files",
+    "send_message_with_attachment",
+}
+
+
+def _run_handler(impl):
+    """Invoke a handler with its test_payload, awaiting if it's async."""
+    result = impl.handler(impl.metadata.test_payload)
+    if inspect.iscoroutine(result):
+        result = asyncio.run(result)
+    return result
+
+
+_LOADED = False
+
+
+def _ensure_actions_loaded():
+    global _LOADED
+    if not _LOADED:
+        load_actions_from_directories(paths_to_scan=["app/data/action"])
+        _LOADED = True
+
+
+def test_action_registry_loads():
+    _ensure_actions_loaded()
+    actions = registry_instance.list_all_actions()
+    assert len(actions) > 100, f"expected >100 actions, got {len(actions)}"
+
+
+def test_critical_routing_actions_exist():
+    """Conversation-mode routing in ActionRouter pulls these by name."""
+    _ensure_actions_loaded()
+    actions = registry_instance.list_all_actions()
+    for required in ("send_message", "task_start", "ignore"):
+        assert required in actions, f"missing core routing action: {required}"
+
+
+def test_representative_integration_actions_exist():
+    _ensure_actions_loaded()
+    actions = registry_instance.list_all_actions()
+    for required in ("send_gmail", "list_gmail", "send_slack_message"):
+        assert required in actions, f"missing integration action: {required}"
+
+
+def test_web_search_simulated_end_to_end():
+    """web_search has test_payload={simulated_mode: True} — exercise it."""
+    _ensure_actions_loaded()
+    impl = registry_instance.get_action_implementation("web_search", platform.system().lower())
+    assert impl is not None, "web_search has no impl for this platform"
+    assert impl.metadata.test_payload is not None, "web_search has no test_payload"
+
+    result = _run_handler(impl)
+    assert isinstance(result, dict), f"expected dict, got {type(result).__name__}"
+    assert result.get("status") in ("success", "ok"), f"non-success status: {result}"
+    assert result.get("result_count", 0) > 0, "simulated search returned no results"
+
+
+def test_all_testable_actions_smoke():
+    """Same loop as run_actions_tests.py — every action with test_payload.
+
+    Acts as a tripwire: if anyone adds test_payload to a new action, this
+    catches the smoke regression for free.
+    """
+    _ensure_actions_loaded()
+    testable = registry_instance.get_testable_actions(platform.system().lower())
+    assert testable, "registry reports zero testable actions"
+
+    failures = []
+    skipped = []
+    for impl in testable:
+        if impl.metadata.name in KNOWN_BROKEN_TEST_PAYLOADS:
+            skipped.append(impl.metadata.name)
+            continue
+        try:
+            result = _run_handler(impl)
+            if not isinstance(result, dict):
+                failures.append((impl.metadata.name, f"non-dict: {type(result).__name__}"))
+                continue
+            status = result.get("status")
+            if status not in ("success", "ok", "ignored", "completed", "queued", None):
+                failures.append((impl.metadata.name, f"status={status}: {result.get('message', '')}"))
+        except Exception as e:
+            failures.append((impl.metadata.name, f"raised: {type(e).__name__}: {e}"))
+
+    if skipped:
+        print(f"\nskipped {len(skipped)} known-broken: {skipped}")
+    assert not failures, "testable actions failed:\n" + "\n".join(f"  {n}: {m}" for n, m in failures)
diff --git a/tests/test_token_attribution.py b/tests/test_token_attribution.py
new file mode 100644
index 00000000..f9cf7984
--- /dev/null
+++ b/tests/test_token_attribution.py
@@ -0,0 +1,141 @@
+# -*- coding: utf-8 -*-
+"""
+Tests for per-task LLM token attribution.
+
+Verifies that `attribute_usage_to_current_task` correctly bumps the
+cumulative token counters on the active Task and emits a TASK_TOKEN_UPDATE
+event on the bus so the browser can tick its per-task token display.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from agent_core.core.hooks.types import UsageEventData
+from agent_core.core.task.task import Task
+from app.state.agent_state import STATE
+from app.ui_layer.events.event_bus import EventBus
+from app.ui_layer.events.event_types import UIEvent, UIEventType
+from app.usage.task_attribution import attribute_usage_to_current_task
+
+
+@pytest.fixture
+def fresh_state():
+    """Snapshot and restore STATE.current_task / STATE.event_bus per test."""
+    prev_task = STATE.current_task
+    prev_bus = STATE.event_bus
+    yield
+    STATE.current_task = prev_task
+    STATE.event_bus = prev_bus
+
+
+def _make_event(input_tokens=100, output_tokens=50, cached_tokens=20):
+    return UsageEventData(
+        service_type="llm_anthropic",
+        provider="anthropic",
+        model="claude-sonnet-4-6",
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cached_tokens=cached_tokens,
+    )
+
+
+def test_no_active_task_is_noop(fresh_state):
+    """When no task is active, attribution is a silent no-op."""
+    STATE.current_task = None
+    STATE.event_bus = EventBus()
+    # Must not raise
+    attribute_usage_to_current_task(_make_event())
+    assert STATE.event_bus.get_history() == []
+
+
+def test_increments_counters_on_active_task(fresh_state):
+    """A single call bumps the task's three counters."""
+    task = Task(id="t1", name="test", instruction="x")
+    STATE.current_task = task
+    STATE.event_bus = EventBus()
+
+    attribute_usage_to_current_task(_make_event(100, 50, 20))
+
+    assert task.input_tokens == 100
+    assert task.output_tokens == 50
+    assert task.cache_tokens == 20
+
+
+def test_accumulates_across_multiple_calls(fresh_state):
+    """Counters accumulate, not overwrite."""
+    task = Task(id="t2", name="test", instruction="x")
+    STATE.current_task = task
+    STATE.event_bus = EventBus()
+
+    attribute_usage_to_current_task(_make_event(100, 50, 20))
+    attribute_usage_to_current_task(_make_event(40, 10, 5))
+    attribute_usage_to_current_task(_make_event(7, 3, 0))
+
+    assert task.input_tokens == 147
+    assert task.output_tokens == 63
+    assert task.cache_tokens == 25
+
+
+def test_emits_task_token_update_event(fresh_state):
+    """Each attribution emits a TASK_TOKEN_UPDATE carrying running totals."""
+    task = Task(id="t3", name="test", instruction="x")
+    STATE.current_task = task
+    bus = EventBus()
+    STATE.event_bus = bus
+
+    captured: list[UIEvent] = []
+    bus.subscribe(UIEventType.TASK_TOKEN_UPDATE, captured.append)
+
+    attribute_usage_to_current_task(_make_event(100, 50, 20))
+    attribute_usage_to_current_task(_make_event(40, 10, 5))
+
+    assert len(captured) == 2
+
+    # First event: counters at first call's values
+    assert captured[0].type == UIEventType.TASK_TOKEN_UPDATE
+    assert captured[0].task_id == "t3"
+    assert captured[0].data == {
+        "task_id": "t3",
+        "input_tokens": 100,
+        "output_tokens": 50,
+        "cache_tokens": 20,
+    }
+
+    # Second event: cumulative running totals
+    assert captured[1].data == {
+        "task_id": "t3",
+        "input_tokens": 140,
+        "output_tokens": 60,
+        "cache_tokens": 25,
+    }
+
+
+def test_works_without_event_bus(fresh_state):
+    """If no bus is registered, counters still update; no crash."""
+    task = Task(id="t4", name="test", instruction="x")
+    STATE.current_task = task
+    STATE.event_bus = None  # explicit
+
+    attribute_usage_to_current_task(_make_event(100, 50, 20))
+
+    assert task.input_tokens == 100
+    assert task.output_tokens == 50
+    assert task.cache_tokens == 20
+
+
+def test_handles_none_token_fields_as_zero(fresh_state):
+    """Pre-existing tasks may have None token fields (legacy data)."""
+    task = Task(id="t5", name="test", instruction="x")
+    # Simulate legacy Task loaded from older persistence with no token fields
+    task.input_tokens = None  # type: ignore[assignment]
+    task.output_tokens = None  # type: ignore[assignment]
+    task.cache_tokens = None  # type: ignore[assignment]
+    STATE.current_task = task
+    STATE.event_bus = EventBus()
+
+    attribute_usage_to_current_task(_make_event(10, 5, 1))
+
+    assert task.input_tokens == 10
+    assert task.output_tokens == 5
+    assert task.cache_tokens == 1