diff --git a/AGENTS.md b/AGENTS.md
index adf6984..60cee87 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,6 +51,7 @@ This document is the LeapFlow engineering collaboration contract. It is not only
 - Consider affected user journeys before changing shared flows; do not introduce regressions, broken links, or worse experiences in adjacent paths
 - Keep common paths transparent: long-running work must stream progress, surface recoverable errors clearly, and avoid silent stalls.
 - For context assembly, prefer manifest-driven progressive disclosure over shortcuts or intent-handler sprawl: expose compact capability indexes, selected schemas, and targeted memory only when the current plan needs them.
+- Avoid rule-based natural-language fitting by default. Do not add keyword/action-verb/alias enumerations, intent-handler taxonomies, or brittle routing rules when LLM-native capability disclosure, manifests, schemas, protocols, or configuration-driven contracts can solve the problem. If a rule-based method is truly unavoidable for a stable protocol boundary, offline fallback, or safety hard gate, explain the necessity, scope, alternatives, and rollback path to a human and obtain explicit second confirmation before implementation.
 - Preserve security and audit paths: dangerous actions, file writes, outbound messages, credentials, and path access must flow through the existing policy, approval, redaction, and audit mechanisms.
 - Maintain backward-compatible migrations for persistent state, configuration, skills, trajectories, sessions, and profile data.
 - Write unit tests before or alongside the implementation
@@ -62,6 +63,7 @@ This document is the LeapFlow engineering collaboration contract. It is not only
 ## Review Requirements
 
 - **Deep review for large changes**: When a change substantially affects architecture, runtime behavior, user flows, persistence, safety, or multiple modules, perform an additional deep review before considering the work complete.
+- **Human confirmation for TUI changes**: Any TUI layout or interaction-logic change requires a second human confirmation before it is considered ready.
 - **Design goal check**: Verify that the implementation actually achieves the intended design goal and is not just a local patch.
 - **Optimality check**: Evaluate whether the solution is the simplest robust design, avoids unnecessary abstractions, and fits the existing architecture.
 - **Regression impact check**: Inspect affected modules and user journeys for logic bugs, degraded UX, broken compatibility, slower feedback, weaker diagnostics, or worse failure recovery.
@@ -90,7 +92,7 @@ This document is the LeapFlow engineering collaboration contract. It is not only
 - Hardcoded paths, URLs, thresholds without config escape hatch
 - Chinese comments in source code (English only)
 - Speculative infrastructure: no hooks or extension points without a concrete consumer
-- Shortcut-style natural-language fitting and large intent-handler taxonomies; use stable runtime gates plus capability manifests instead.
+- Shortcut-style natural-language fitting and large intent-handler taxonomies; use stable runtime gates plus capability manifests instead. Rule-based keyword/action-verb/alias matching is prohibited by default and requires explicit human second confirmation before implementation when unavoidable.
 - Bare `except:` clauses — always specify the exception type
 - `# TODO: implement` stubs — implement or don't commit
 
diff --git a/pyproject.toml b/pyproject.toml
index 62d0163..32fefec 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -54,6 +54,9 @@ version = {attr = "leapflow.version.__version__"}
 where = ["src"]
 include = ["leapflow*"]
 
+[tool.setuptools.package-data]
+"leapflow.gateway.action_packs" = ["*.yaml"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 pythonpath = ["src", "tests"]
diff --git a/src/leapflow/cli/commands/interactive.py b/src/leapflow/cli/commands/interactive.py
index f9b0813..64caeaa 100644
--- a/src/leapflow/cli/commands/interactive.py
+++ b/src/leapflow/cli/commands/interactive.py
@@ -31,6 +31,11 @@
 _last_hint: Optional["PredictionCandidate"] = None
 
 
+def _is_app_command(canonical: str) -> bool:
+    """Return true only for `/app` or `/app ...`, not `/apple`."""
+    return canonical == "app" or canonical.startswith("app ")
+
+
 async def _prompt_stop_daemon_on_exit(
     client: "DaemonClient",
     settings: Any,
@@ -253,6 +258,7 @@ async def cmd_interactive(ctx: "Context", *, resume_id: Optional[str] = None) ->
         handle_model,
         handle_clear,
         handle_gateway,
+        handle_app,
     )
     from leapflow.utils.terminal_io import TerminalIOProvider
     from leapflow.engine.session import SessionMode
@@ -570,6 +576,12 @@ async def handle_input(text: str) -> None:
                 handle_gateway(ctx, console, cmd_args)
                 return
 
+            if _is_app_command(canonical):
+                app_args = cmd_text[len("app"):].strip()
+                await handle_app(ctx, console, app_args)
+                _update_status()
+                return
+
             if canonical == "usage":
                 handle_usage(ctx, console, cmd_args)
                 return
@@ -808,6 +820,7 @@ async def cmd_interactive_daemon(
     from leapflow.cli.commands.registry import completion_entries
     from leapflow.cli.commands.router import CommandRouter, render_command_result
     from leapflow.cli.commands.slash_handlers import (
+        render_app_payload,
         render_model_payload,
         render_tools_payload,
         render_usage_payload,
@@ -1155,6 +1168,18 @@ async def handle_input(text: str) -> None:
                     return
                 render_model_payload(console, payload)
                 return
+            if _is_app_command(canonical):
+                app_args = invocation.text[len("app"):].strip()
+                try:
+                    payload = await bridge.call(
+                        lambda current_client: current_client.app_command(app_args),
+                        description="app command",
+                    )
+                except Exception as exc:
+                    console.warning(f"App Connector unavailable: {exc}")
+                    return
+                render_app_payload(console, payload)
+                return
             if canonical == "run":
                 if not cmd_args:
                     console.warning("Usage: /run <trigger>")
diff --git a/src/leapflow/cli/commands/registry.py b/src/leapflow/cli/commands/registry.py
index 2d5245a..f587742 100644
--- a/src/leapflow/cli/commands/registry.py
+++ b/src/leapflow/cli/commands/registry.py
@@ -117,6 +117,16 @@ def supports_runtime(self, runtime: CommandRuntime) -> bool:
     # Gateway
     CommandDef("gateway", "Show connected platforms and gateway status", "Gateway", effect=CommandEffect.EXTERNAL),
 
+    # App Connector
+    CommandDef("app", "List supported external apps or open an app setup guide", "App Connector", args_hint="[platform]", supports_daemon=True),
+    CommandDef("app list", "List supported external apps", "App Connector", supports_daemon=True),
+    CommandDef("app status", "Show App Connector status", "App Connector", args_hint="[platform]", supports_daemon=True),
+    CommandDef("app connect", "Connect a supported external app", "App Connector", args_hint="<platform> [--option value]", effect=CommandEffect.EXTERNAL, execution=CommandExecution.SHORT_OPERATION),
+    CommandDef("app disconnect", "Disconnect an external app but keep configuration", "App Connector", args_hint="<platform>", effect=CommandEffect.EXTERNAL, execution=CommandExecution.SHORT_OPERATION),
+    CommandDef("app remove", "Remove an app configuration", "App Connector", args_hint="<platform>", effect=CommandEffect.DESTRUCTIVE, execution=CommandExecution.SHORT_OPERATION),
+    CommandDef("app events", "Inspect or control an app event source", "App Connector", args_hint="[status|start|stop] <platform>", effect=CommandEffect.EXTERNAL, execution=CommandExecution.SHORT_OPERATION),
+    CommandDef("app actions", "List App Connector action domains", "App Connector", args_hint="<platform>", supports_daemon=True),
+
     # Scheduler
     CommandDef("arm", "Schedule a skill for timed execution", "Scheduler", args_hint="<skill> <cron>"),
     CommandDef("tasks", "List scheduled tasks", "Scheduler"),
diff --git a/src/leapflow/cli/commands/slash_handlers.py b/src/leapflow/cli/commands/slash_handlers.py
index bbf2161..6233115 100644
--- a/src/leapflow/cli/commands/slash_handlers.py
+++ b/src/leapflow/cli/commands/slash_handlers.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import os
+import shlex
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -322,6 +323,416 @@ def handle_gateway(ctx: "Context", console: "LeapConsole", args: str) -> None:
     ))
 
 
+def _app_usage() -> dict[str, Any]:
+    return {
+        "ok": False,
+        "error": "Usage: /app [platform] | /app status [platform] | /app connect <platform> [--option value] | /app disconnect <platform> | /app remove <platform> | /app events [status|start|stop] <platform> | /app actions <platform>",
+        "next_actions": ("/app", "/app <platform>", "/app status <platform>"),
+    }
+
+
+def _parse_app_options(tokens: list[str]) -> tuple[dict[str, str], str]:
+    options: dict[str, str] = {}
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if not token.startswith("--") or token == "--":
+            return {}, f"Unexpected argument: {token}"
+        key_value = token[2:]
+        if "=" in key_value:
+            key, value = key_value.split("=", 1)
+            if not key:
+                return {}, f"Invalid option: {token}"
+            options[key] = value
+            index += 1
+            continue
+        if index + 1 >= len(tokens):
+            return {}, f"Missing value for option: {token}"
+        key = key_value
+        if not key:
+            return {}, f"Invalid option: {token}"
+        options[key] = tokens[index + 1]
+        index += 2
+    return options, ""
+
+
+def _parse_app_params(args: str) -> dict[str, Any]:
+    try:
+        tokens = shlex.split(args)
+    except ValueError as exc:
+        return {"ok": False, "error": f"Invalid /app arguments: {exc}"}
+
+    if not tokens or tokens[0].lower() == "list":
+        if len(tokens) > 1:
+            return _app_usage()
+        return {"ok": True, "params": {"action": "list"}, "view": "list"}
+
+    head = tokens[0].lower()
+    if head == "status":
+        if len(tokens) > 2:
+            return _app_usage()
+        params: dict[str, Any] = {"action": "status"}
+        if len(tokens) == 2:
+            params["platform"] = tokens[1].lower()
+        return {"ok": True, "params": params, "view": "status"}
+
+    if head == "connect":
+        if len(tokens) < 2:
+            return _app_usage()
+        options, error = _parse_app_options(tokens[2:])
+        if error:
+            return {
+                "ok": False,
+                "error": error,
+                "next_actions": ("/app connect <platform> --<option> <value>",),
+            }
+        params = {"action": "connect", "platform": tokens[1].lower()}
+        if options:
+            params["options"] = options
+        return {"ok": True, "params": params, "view": "connect"}
+
+    if head in {"disconnect", "remove"}:
+        if len(tokens) != 2:
+            return _app_usage()
+        return {
+            "ok": True,
+            "params": {"action": head, "platform": tokens[1].lower()},
+            "view": head,
+        }
+
+    if head == "events":
+        if len(tokens) == 2:
+            return {
+                "ok": True,
+                "params": {"action": "events_status", "platform": tokens[1].lower()},
+                "view": "events",
+            }
+        if len(tokens) == 3 and tokens[1].lower() in {"status", "start", "stop"}:
+            event_action = tokens[1].lower()
+            action = "events_status" if event_action == "status" else f"events_{event_action}"
+            return {
+                "ok": True,
+                "params": {"action": action, "platform": tokens[2].lower()},
+                "view": "events",
+            }
+        return _app_usage()
+
+    if head == "actions":
+        if len(tokens) != 2:
+            return _app_usage()
+        return {"ok": True, "platform": tokens[1].lower(), "view": "actions"}
+
+    if len(tokens) == 1:
+        return {
+            "ok": True,
+            "params": {"action": "guide", "platform": tokens[0].lower()},
+            "view": "guide",
+        }
+
+    return _app_usage()
+
+
+def _resolve_app_platform(gw: Any, platform: str) -> tuple[str, str]:
+    if not platform:
+        return "", ""
+    manifests = getattr(gw, "manifests", {}) or {}
+    if platform in manifests:
+        return platform, ""
+    folded = platform.casefold()
+    matches = [pid for pid in manifests if str(pid).casefold() == folded]
+    if len(matches) == 1:
+        return matches[0], ""
+    return "", f"Unknown platform: {platform}"
+
+
+def _available_app_ids(gw: Any) -> list[str]:
+    manifests = getattr(gw, "manifests", {}) or {}
+    return sorted(str(platform_id) for platform_id in manifests)
+
+
+def _coerce_app_option(field: Any, value: str) -> tuple[Any, str]:
+    choices = tuple(getattr(field, "choices", ()) or ())
+    if choices and value not in choices:
+        return None, f"Invalid value for --{field.key}: {value}. Choices: {', '.join(map(str, choices))}"
+
+    field_type = str(getattr(field, "field_type", "string") or "string").lower()
+    if field_type in {"string", "choice"}:
+        return value, ""
+    if field_type in {"integer", "int"}:
+        try:
+            return int(value), ""
+        except ValueError:
+            return None, f"Invalid integer for --{field.key}: {value}"
+    if field_type in {"number", "float"}:
+        try:
+            return float(value), ""
+        except ValueError:
+            return None, f"Invalid number for --{field.key}: {value}"
+    if field_type in {"boolean", "bool"}:
+        lowered = value.casefold()
+        if lowered in {"1", "true", "yes", "on"}:
+            return True, ""
+        if lowered in {"0", "false", "no", "off"}:
+            return False, ""
+        return None, f"Invalid boolean for --{field.key}: {value}"
+    return value, ""
+
+
+def _validate_app_options(manifest: Any, options: dict[str, str]) -> tuple[dict[str, Any], str]:
+    if not options:
+        return {}, ""
+    fields = {str(field.key): field for field in getattr(manifest, "options", ())}
+    unknown = sorted(key for key in options if key not in fields)
+    if unknown:
+        available = ", ".join(sorted(fields)) or "no options"
+        return {}, f"Unknown option(s): {', '.join(unknown)}. Available options: {available}"
+
+    coerced: dict[str, Any] = {}
+    for key, value in options.items():
+        converted, error = _coerce_app_option(fields[key], value)
+        if error:
+            return {}, error
+        coerced[key] = converted
+    return coerced, ""
+
+
+async def build_app_payload(ctx: "Context", args: str = "") -> dict[str, Any]:
+    """Build a serializable App Connector slash-command payload."""
+    gw = getattr(ctx, "gateway_server", None)
+    if gw is None:
+        return {
+            "ok": False,
+            "error": "Gateway is not initialised in this session.",
+            "next_actions": ("Start an in-process LeapFlow session", "Use /help to inspect runtime support"),
+        }
+
+    parsed = _parse_app_params(args)
+    if not parsed.get("ok"):
+        parsed.setdefault("available", _available_app_ids(gw))
+        return parsed
+
+    from leapflow.tools.gateway_tool import platform_action_capability_summary, platform_connect_handler, set_gateway_server
+
+    set_gateway_server(gw)
+    if parsed.get("view") == "actions":
+        platform, error = _resolve_app_platform(gw, str(parsed.get("platform") or ""))
+        if error:
+            return {"ok": False, "error": error, "available": _available_app_ids(gw)}
+        manifest = gw.manifests.get(platform)
+        if manifest is None:
+            return {"ok": False, "error": f"Unknown platform: {platform}", "available": _available_app_ids(gw)}
+        actions = dict(getattr(manifest, "actions", {}) or {})
+        action_summaries = platform_action_capability_summary(platform)
+        return {
+            "ok": True,
+            "view": "actions",
+            "platform": platform,
+            "name": getattr(manifest, "display_name", platform),
+            "action_pack": str(actions.get("pack") or ""),
+            "actions": [item["name"] for item in action_summaries if item.get("name")],
+            "action_details": action_summaries,
+        }
+
+    params = dict(parsed.get("params") or {})
+    platform = str(params.get("platform") or "")
+    if platform:
+        resolved, error = _resolve_app_platform(gw, platform)
+        if error:
+            return {"ok": False, "error": error, "available": _available_app_ids(gw)}
+        params["platform"] = resolved
+        manifest = gw.manifests.get(resolved)
+        if manifest is not None and params.get("action") == "connect":
+            options, option_error = _validate_app_options(
+                manifest,
+                dict(params.get("options") or {}),
+            )
+            if option_error:
+                return {
+                    "ok": False,
+                    "error": option_error,
+                    "available": _available_app_ids(gw),
+                    "next_actions": (f"/app {resolved}", f"/app connect {resolved}"),
+                }
+            if options:
+                params["options"] = options
+
+    result = await platform_connect_handler(params)
+    view = str(parsed.get("view") or "")
+    if params.get("action") == "connect" and result.get("setup_guide"):
+        view = "guide"
+    return {
+        "ok": bool(result.get("ok")),
+        "view": view,
+        "params": params,
+        "result": result,
+    }
+
+
+def _append_result_metadata(lines: list[str], result: dict[str, Any]) -> None:
+    diagnostics = result.get("diagnostics") or result.get("metadata")
+    if isinstance(diagnostics, dict) and diagnostics:
+        for key in ("backend_kind", "profile", "identity", "auth_status", "configured", "current_mode"):
+            if diagnostics.get(key) is not None:
+                lines.append(f"  {key}: {diagnostics[key]}")
+    recovery_hint = result.get("recovery_hint")
+    if recovery_hint:
+        lines.append(f"  recovery: {recovery_hint}")
+    next_steps = result.get("next_steps")
+    if isinstance(next_steps, list) and next_steps:
+        lines.append("  next steps:")
+        lines.extend(f"    - {step}" for step in next_steps)
+
+
+def render_app_payload(console: "LeapConsole", payload: dict[str, Any]) -> None:
+    """Render a serializable App Connector slash-command payload."""
+    from rich.panel import Panel
+    from rich.table import Table
+    from rich.text import Text
+
+    if not payload.get("ok"):
+        result = dict(payload.get("result") or {})
+        message = (
+            payload.get("error")
+            or result.get("error")
+            or result.get("detail")
+            or "App command failed."
+        )
+        console.warning(str(message))
+        lines: list[str] = []
+        _append_result_metadata(lines, result)
+        for line in lines:
+            console.system(line)
+        available = payload.get("available")
+        if isinstance(available, list) and available:
+            console.system("Available: " + ", ".join(str(item) for item in available))
+        for action in payload.get("next_actions") or ():
+            console.system(f"  → {action}")
+        return
+
+    result = dict(payload.get("result") or {})
+    view = str(payload.get("view") or "")
+    if view == "list":
+        platforms = list(result.get("platforms") or [])
+        table = Table(title="App Connector", show_header=True, header_style="bold", border_style="bright_black")
+        table.add_column("App", style="cyan")
+        table.add_column("ID", style="bold")
+        table.add_column("State")
+        table.add_column("Category")
+        table.add_column("Next")
+        for entry in platforms:
+            platform_id = str(entry.get("id") or "")
+            state = str(entry.get("state") or "available")
+            style = "green" if state == "connected" else ("yellow" if state == "configured" else "dim")
+            table.add_row(
+                str(entry.get("name") or platform_id),
+                platform_id,
+                f"[{style}]{state}[/]",
+                str(entry.get("category") or ""),
+                f"/app {platform_id}",
+            )
+        console.print(table)
+        console.system("Next: /app <platform> · /app status <platform> · /app connect <platform>")
+        return
+
+    if view == "guide":
+        info = Text()
+        info.append(str(result.get("setup_guide") or "No setup guide available.") + "\n")
+        steps = result.get("setup_steps") or []
+        if steps:
+            info.append("\nSteps\n", style="bold")
+            for index, step in enumerate(steps, start=1):
+                info.append(f"  {index}. {step}\n")
+        preflight = result.get("preflight_checks") or []
+        if preflight:
+            info.append("\nPreflight\n", style="bold")
+            for check in preflight:
+                command = check.get("command") or ""
+                label = check.get("label") or check.get("key") or "check"
+                info.append(f"  - {label}: {command}\n")
+        fields = result.get("required_fields") or []
+        if fields:
+            info.append("\nRequired fields\n", style="bold")
+            for field in fields:
+                required = "required" if field.get("required") else "optional"
+                info.append(f"  - {field.get('key')}: {field.get('label')} ({required})\n")
+        console_url = result.get("console_url")
+        if console_url:
+            info.append(f"\nConsole: {console_url}\n", style="dim")
+        platform = str(result.get("platform") or payload.get("params", {}).get("platform") or "App")
+        console.print(Panel(info, title=f"[bold cyan]{platform} setup[/]", border_style="bright_black", padding=(0, 2)))
+        platform_id = str(payload.get("params", {}).get("platform") or "<platform>")
+        if fields:
+            console.system(
+                "Next: provide required credentials through the guided chat flow, "
+                f"then run /app connect {platform_id}"
+            )
+        else:
+            console.system(f"Next: /app connect {platform_id}")
+        return
+
+    if view == "status":
+        platforms = result.get("platforms")
+        if isinstance(platforms, list):
+            table = Table(title="App Status", show_header=True, header_style="bold", border_style="bright_black")
+            table.add_column("ID", style="bold")
+            table.add_column("Connected")
+            table.add_column("Detail")
+            for entry in platforms:
+                detail = str(entry.get("error") or entry.get("uptime") or "available")
+                table.add_row(str(entry.get("id") or ""), "yes" if entry.get("connected") else "no", detail)
+            console.print(table)
+            return
+        lines = [f"platform: {result.get('platform')}", f"connected: {bool(result.get('connected'))}"]
+        if result.get("error"):
+            lines.append(f"detail: {result['error']}")
+        if result.get("uptime"):
+            lines.append(f"uptime: {result['uptime']}")
+        _append_result_metadata(lines, result)
+        console.print(Panel("\n".join(lines), title="[bold cyan]App Status[/]", border_style="bright_black", padding=(0, 2)))
+        return
+
+    if view == "actions":
+        action_names = list(payload.get("actions") or [])
+        action_details = list(payload.get("action_details") or [])
+        lines = [f"platform: {payload.get('name')}"]
+        if payload.get("action_pack"):
+            lines.append(f"action pack: {payload['action_pack']}")
+        if action_names:
+            lines.append("registered actions:")
+            details_by_name = {str(item.get("name")): item for item in action_details}
+            for name in action_names:
+                detail = details_by_name.get(name, {})
+                description = str(detail.get("description") or "").strip()
+                suffix = f" — {description}" if description else ""
+                lines.append(f"  - {name}{suffix}")
+        else:
+            lines.append("registered actions: none")
+        console.print(Panel("\n".join(lines), title="[bold cyan]App Actions[/]", border_style="bright_black", padding=(0, 2)))
+        return
+
+    if result.get("ok"):
+        platform = result.get("platform") or payload.get("params", {}).get("platform") or "App"
+        status = result.get("status") or result.get("detail") or "ok"
+        lines = [f"{platform}: {status}"]
+        _append_result_metadata(lines, result)
+        console.success("App command completed")
+        console.system("\n".join(lines))
+        return
+
+    message = result.get("error") or result.get("detail") or "App command failed."
+    console.warning(str(message))
+    lines: list[str] = []
+    _append_result_metadata(lines, result)
+    for line in lines:
+        console.system(line)
+
+
+async def handle_app(ctx: "Context", console: "LeapConsole", args: str) -> None:
+    """Manage external App Connector integrations from slash commands."""
+    render_app_payload(console, await build_app_payload(ctx, args))
+
+
+
 def handle_clear(ctx: "Context", console: "LeapConsole", args: str) -> None:
     """Clear the terminal screen."""
     os.system("cls" if os.name == "nt" else "clear")
diff --git a/src/leapflow/cli/context.py b/src/leapflow/cli/context.py
index 1ac92e3..1cbecf2 100644
--- a/src/leapflow/cli/context.py
+++ b/src/leapflow/cli/context.py
@@ -583,6 +583,15 @@ def _sync_engine_runtime_budget(self, settings: Settings) -> None:
             )
         self.engine.set_tool_result_budget(dynamic_result_budget)
         self.engine.set_model_capabilities(self._build_model_capability_registry(settings))
+
+        compressor = getattr(self.engine, "_compressor", None)
+        if compressor is not None and hasattr(compressor, "reconfigure"):
+            token_budget = max(1, int(context_length * settings.context_hard_limit_ratio))
+            compressor.reconfigure(
+                token_budget=token_budget,
+                context_length=context_length,
+            )
+
         logger.debug("Model capability registry wired")
 
     @staticmethod
@@ -1587,12 +1596,14 @@ async def _summarize_via_llm(prompt: str) -> str:
             )
             return (resp.content or "").strip()
 
+        ctx_len = self._effective_llm_context_length(settings)
         compressor_config = CompressorConfig(
+            token_budget=max(1, int(ctx_len * settings.context_hard_limit_ratio)),
+            context_length=ctx_len,
             threshold=settings.compress_threshold,
             keep_tail=settings.compress_keep_tail,
             max_output_chars=settings.max_tool_output_chars,
             summarize_fn=_summarize_via_llm if settings.has_llm_credentials else None,
-            token_count_fn=lambda text: len(text) // 4,
         )
 
         # ── Initialize DuckDBConversationStore ──
diff --git a/src/leapflow/cli/tui_app/app.py b/src/leapflow/cli/tui_app/app.py
index d3bfc43..5fb9b2b 100644
--- a/src/leapflow/cli/tui_app/app.py
+++ b/src/leapflow/cli/tui_app/app.py
@@ -23,6 +23,7 @@
 
 import asyncio
 import os
+import shutil
 import time
 from collections import deque
 from pathlib import Path
@@ -727,6 +728,9 @@ def _build_input_area(
         return area
 
     def _build_application(self) -> Application[Any]:
+        no_approval = Condition(lambda: self._approval_modal is None)
+        has_approval = Condition(lambda: self._approval_modal is not None)
+
         spinner = Window(
             content=FormattedTextControl(self._spinner_fragments),
             height=self._spinner_height,
@@ -743,8 +747,7 @@ def _build_application(self) -> Application[Any]:
             wrap_lines=False,
             style="class:status-bar",
         )
-        root = HSplit([spinner, status_gap, status_bar, self._input_area])
-        approval_overlay = ConditionalContainer(
+        approval_panel = ConditionalContainer(
             Window(
                 content=FormattedTextControl(self._approval_fragments),
                 height=self._approval_height,
@@ -752,8 +755,15 @@ def _build_application(self) -> Application[Any]:
                 dont_extend_height=True,
                 style="class:approval.modal",
             ),
-            filter=Condition(lambda: self._approval_modal is not None),
+            filter=has_approval,
         )
+        root = HSplit([
+            ConditionalContainer(spinner, filter=no_approval),
+            approval_panel,
+            ConditionalContainer(status_gap, filter=no_approval),
+            status_bar,
+            ConditionalContainer(self._input_area, filter=no_approval),
+        ])
         layout = Layout(
             FloatContainer(
                 content=root,
@@ -767,13 +777,6 @@ def _build_application(self) -> Application[Any]:
                             display_arrows=True,
                         ),
                     ),
-                    Float(
-                        top=0,
-                        bottom=2,
-                        left=2,
-                        right=2,
-                        content=approval_overlay,
-                    ),
                 ],
             )
         )
@@ -993,17 +996,22 @@ def _placeholder_text(self) -> str:
             return f"{self._pending_input.qsize()} queued · /pause hold · /queue view · /drop <id> remove"
         return "Ask LeapFlow… /help commands · /status runtime · /queue tasks"
 
+    def _approval_max_lines(self) -> int:
+        """Terminal-aware max height for the inline approval panel."""
+        terminal_lines = shutil.get_terminal_size((80, 24)).lines
+        return max(8, terminal_lines - 2)
+
     def _approval_fragments(self) -> list[tuple[str, str]]:
         modal = self._approval_modal
         if modal is None:
             return []
-        return modal.fragments()
+        return modal.fragments(max_lines=self._approval_max_lines())
 
     def _approval_height(self) -> int:
         modal = self._approval_modal
         if modal is None:
             return 0
-        return modal.line_count()
+        return modal.line_count(max_lines=self._approval_max_lines())
 
     def _spinner_fragments(self) -> list[tuple[str, str]]:
         if not self._spinner_text:
diff --git a/src/leapflow/cli/tui_app/approval_modal.py b/src/leapflow/cli/tui_app/approval_modal.py
index f8ec5a9..420363d 100644
--- a/src/leapflow/cli/tui_app/approval_modal.py
+++ b/src/leapflow/cli/tui_app/approval_modal.py
@@ -3,6 +3,10 @@
 Renders a bordered panel with action summary, detail, risk reason,
 and selectable choices — fully within the prompt_toolkit layout.
 Keyboard: ↑/↓ navigate, Enter confirm, Esc deny, or type shortcut keys.
+
+Height adaptation: when ``max_lines`` is passed to :meth:`fragments` or
+:meth:`line_count`, the modal trims variable content (detail → reason →
+timeout → summary) while always preserving the frame and choices.
 """
 from __future__ import annotations
 
@@ -24,11 +28,13 @@
 from leapflow.security.redact import redact_sensitive_text
 
 Fragment = tuple[str, str]
+_ContentLine = list[Fragment]
 
 _MIN_WIDTH = 58
 _MAX_WIDTH = 104
 _DETAIL_LINES = 3
 _REASON_LINES = 2
+_MIN_MODAL_HEIGHT = 8
 
 
 @dataclass
@@ -83,31 +89,18 @@ def resolve(self, decision: ApprovalDecision) -> None:
         if not self.future.done():
             self.future.set_result(decision)
 
-    def fragments(self) -> list[Fragment]:
-        """Build all fragments for the modal — no height truncation.
-
-        The prompt_toolkit Window handles clipping/scrolling.
-        Content lines are limited by static caps (_DETAIL_LINES,
-        _REASON_LINES) to keep the panel concise.
-        """
-        width = _modal_width()
-        inner = width - 4
-        title = f"⚠ {title_for_approval(self.request)}"
-
-        lines: list[list[Fragment]] = []
+    # ── Content section builders ──────────────────────────────────────
 
-        # ── Top border ──
-        lines.append(_border_top(width, title))
-
-        # ── Summary ──
+    def _summary_lines(self, inner: int) -> list[_ContentLine]:
         summary = str(self.request.display.get("summary") or self.request.category)
-        for text in _wrap(summary, inner)[:2]:
-            lines.append(_content_line(text, inner, "class:approval.summary"))
-
-        # ── Blank separator ──
+        lines: list[_ContentLine] = [
+            _content_line(t, inner, "class:approval.summary")
+            for t in _wrap(summary, inner)[:2]
+        ]
         lines.append(_content_line("", inner, ""))
+        return lines
 
-        # ── Detail ──
+    def _detail_lines(self, inner: int) -> list[_ContentLine]:
         detail_raw = redact_sensitive_text(self.request.detail, force=True)
         if not self.show_details:
             detail_raw = truncate_detail(
@@ -116,66 +109,119 @@ def fragments(self) -> list[Fragment]:
         detail_wrapped: list[str] = []
         for raw_line in detail_raw.splitlines() or [""]:
             detail_wrapped.extend(_wrap(raw_line, inner - 4))
-        detail_limit = 50 if self.show_details else _DETAIL_LINES
-        for text in detail_wrapped[:detail_limit]:
-            lines.append(_content_line(f"  {text}", inner, "class:approval.detail"))
+        limit = 50 if self.show_details else _DETAIL_LINES
+        return [
+            _content_line(f"  {t}", inner, "class:approval.detail")
+            for t in detail_wrapped[:limit]
+        ]
 
-        # ── Risk reason ──
+    def _reason_lines(self, inner: int) -> list[_ContentLine]:
         reason = str(self.request.display.get("reason") or risk_reason(self.request))
-        if reason:
-            lines.append(_content_line("", inner, ""))
-            lines.append(_content_line(
-                "Why approval is needed:", inner, "class:approval.label",
-            ))
-            for text in _wrap(reason, inner - 4)[:_REASON_LINES]:
-                lines.append(_content_line(f"  {text}", inner, "class:approval.dim"))
-
-        # ── Timeout ──
+        if not reason:
+            return []
+        lines: list[_ContentLine] = [
+            _content_line("", inner, ""),
+            _content_line("Why approval is needed:", inner, "class:approval.label"),
+        ]
+        for t in _wrap(reason, inner - 4)[:_REASON_LINES]:
+            lines.append(_content_line(f"  {t}", inner, "class:approval.dim"))
+        return lines
+
+    def _timeout_lines(self, inner: int) -> list[_ContentLine]:
         remaining = remaining_seconds(self.request)
-        if remaining is not None:
-            lines.append(_content_line(
-                f"  Auto-deny in {int(remaining)}s",
-                inner,
-                "class:approval.dim",
-            ))
-
-        # ── Separator + keyboard hint ──
-        lines.append(_content_line("", inner, ""))
-        lines.append(_content_line(
-            "  ↑↓ navigate · Enter confirm · Esc deny",
-            inner,
-            "class:approval.dim",
-        ))
-
-        # ── Choices ──
+        if remaining is None:
+            return []
+        return [_content_line(
+            f"  Auto-deny in {int(remaining)}s", inner, "class:approval.dim",
+        )]
+
+    def _choices_lines(self, inner: int) -> list[_ContentLine]:
+        lines: list[_ContentLine] = [
+            _content_line("", inner, ""),
+            _content_line(
+                "  ↑↓ navigate · Enter confirm · Esc deny",
+                inner, "class:approval.dim",
+            ),
+        ]
         for idx, choice in enumerate(self.choices):
             selected = idx == self.selected_index
             marker = "▸" if selected else " "
             label = f"  {marker} {idx + 1}. {choice.label}"
             style = "class:approval.selected" if selected else "class:approval.option"
             lines.append(_content_line(label, inner, style))
+        return lines
 
-        # ── Bottom border ──
-        lines.append(_border_bottom(width))
+    # ── Public rendering API ──────────────────────────────────────────
+
+    def fragments(self, *, max_lines: int = 0) -> list[Fragment]:
+        """Build fragments for the modal, adapting to height constraints.
+
+        When *max_lines* > 0, variable content (summary, detail, reason,
+        timeout) is progressively trimmed — in ascending priority order —
+        to fit.  Frame borders and choices are never trimmed.
+        """
+        width = _modal_width()
+        inner = width - 4
+        title = f"⚠ {title_for_approval(self.request)}"
+
+        fixed_top = [_border_top(width, title)]
+        fixed_bottom_content = self._choices_lines(inner)
+        fixed_bottom_border = [_border_bottom(width)]
+        fixed_count = len(fixed_top) + len(fixed_bottom_content) + len(fixed_bottom_border)
+
+        variable_sections = [
+            self._summary_lines(inner),
+            self._detail_lines(inner),
+            self._reason_lines(inner),
+            self._timeout_lines(inner),
+        ]
+
+        budget = (
+            max(0, max_lines - fixed_count)
+            if max_lines > 0
+            else sum(len(s) for s in variable_sections)
+        )
+
+        variable_lines: list[_ContentLine] = []
+        for section in variable_sections:
+            if budget <= 0:
+                break
+            take = section[:budget]
+            variable_lines.extend(take)
+            budget -= len(take)
+
+        all_lines = fixed_top + variable_lines + fixed_bottom_content + fixed_bottom_border
 
-        # ── Flatten to fragment list ──
         result: list[Fragment] = []
-        for line in lines:
+        for line in all_lines:
             result.extend(line)
             result.append(("", "\n"))
         return result
 
-    def line_count(self) -> int:
-        """Return the number of content lines (for Window height sizing)."""
-        count = 1 + 2 + 1  # top border, summary(+blank), blank
-        count += min(_DETAIL_LINES, 3)
-        reason = str(self.request.display.get("reason") or risk_reason(self.request))
-        if reason:
-            count += 1 + 1 + min(_REASON_LINES, 2)
-        if self.request.expires_at is not None:
-            count += 1
-        count += 1 + 1 + len(self.choices) + 1  # blank, hint, choices, bottom
-        return count
+    def line_count(self, *, max_lines: int = 0) -> int:
+        """Return the number of content lines (for Window height sizing).
+
+        When *max_lines* > 0, the count is clamped to that budget while
+        guaranteeing the frame and choices are always accounted for.
+        """
+        inner = _modal_width() - 4
+        fixed = (
+            1  # top border
+            + len(self._choices_lines(inner))
+            + 1  # bottom border
+        )
+        variable = sum(
+            len(s) for s in (
+                self._summary_lines(inner),
+                self._detail_lines(inner),
+                self._reason_lines(inner),
+                self._timeout_lines(inner),
+            )
+        )
+        total = fixed + variable
+        if max_lines > 0:
+            return min(total, max(fixed, max_lines))
+        return total
 
     def _choose(self, choice: ApprovalChoice) -> None:
         if choice.key == "show_details":
diff --git a/src/leapflow/cli/tui_app/stream.py b/src/leapflow/cli/tui_app/stream.py
index 82ad984..afdb900 100644
--- a/src/leapflow/cli/tui_app/stream.py
+++ b/src/leapflow/cli/tui_app/stream.py
@@ -368,6 +368,12 @@ def tool_finished(
                 line.append(result_detail, style="leap.tool" if ok else "leap.error")
             line.append(f" | {_format_elapsed(duration)}", style="leap.tool")
             self._console.print(line)
+            recovery_hint = _metadata_text(metadata, "recovery_hint")
+            if recovery_hint:
+                recovery_line = Text()
+                recovery_line.append("    ↳ recovery: ", style="leap.tool")
+                recovery_line.append(_truncate_detail(recovery_hint, limit=_TOOL_OUTPUT_LIMIT), style="leap.tool")
+                self._console.print(recovery_line)
         self._active_tool = ""
         self._active_tool_detail = ""
         self._tool_start_time = 0.0
diff --git a/src/leapflow/daemon/client.py b/src/leapflow/daemon/client.py
index 990f17a..6747ee6 100644
--- a/src/leapflow/daemon/client.py
+++ b/src/leapflow/daemon/client.py
@@ -138,6 +138,11 @@ async def model_info(self, model_name: str = "") -> dict[str, Any]:
         result = await self.request("model.info", params)
         return dict(result or {})
 
+    async def app_command(self, args: str = "") -> dict[str, Any]:
+        """Return daemon-owned App Connector command payload."""
+        result = await self.request("app.command", {"args": args})
+        return dict(result or {})
+
     async def approval_status(self) -> dict[str, Any]:
         """Return pending daemon approval requests."""
         result = await self.request("approval.status")
diff --git a/src/leapflow/daemon/protocol.py b/src/leapflow/daemon/protocol.py
index 2a0d482..22ac851 100644
--- a/src/leapflow/daemon/protocol.py
+++ b/src/leapflow/daemon/protocol.py
@@ -215,6 +215,10 @@ async def model_info(self, model_name: str = "") -> Dict[str, Any]:
         """Return active model information and switch guidance."""
         ...
 
+    async def app_command(self, args: str = "") -> Dict[str, Any]:
+        """Return an App Connector slash-command payload."""
+        ...
+
     async def approval_status(self) -> Dict[str, Any]:
         """Return pending approval requests."""
         ...
@@ -289,6 +293,7 @@ async def gateway_send(
     "tools.list": "tools_list",
     "usage.summary": "usage_summary",
     "model.info": "model_info",
+    "app.command": "app_command",
     "approval.status": "approval_status",
     "approval.resolve": "approval_resolve",
     "approval.cancel": "approval_cancel",
diff --git a/src/leapflow/daemon/service.py b/src/leapflow/daemon/service.py
index fec0fee..97f014b 100644
--- a/src/leapflow/daemon/service.py
+++ b/src/leapflow/daemon/service.py
@@ -224,6 +224,12 @@ async def model_info(self, model_name: str = "") -> dict[str, Any]:
 
         return build_model_payload(self.context, model_name)
 
+    async def app_command(self, args: str = "") -> dict[str, Any]:
+        """Return daemon-owned App Connector slash-command payload."""
+        from leapflow.cli.commands.slash_handlers import build_app_payload
+
+        return await build_app_payload(self.context, args)
+
     async def approval_status(self) -> dict[str, Any]:
         """Return currently pending daemon approval requests."""
         return {"pending": self._pending_payloads()}
diff --git a/src/leapflow/engine/context_compressor.py b/src/leapflow/engine/context_compressor.py
index 95df4d1..eecaf94 100644
--- a/src/leapflow/engine/context_compressor.py
+++ b/src/leapflow/engine/context_compressor.py
@@ -12,11 +12,13 @@
 - Progressive: lighter stages first, heavier stages only if needed
 - Message-pair integrity: tool-call/tool-result pairs are never split
 - Summarization uses structured prompts with iterative updates
+- All character/token thresholds adapt to the model's context window size
 """
 from __future__ import annotations
 
 import asyncio
 import hashlib
+import json
 import logging
 from dataclasses import dataclass, field
 from typing import Any, Awaitable, Callable, Dict, List, Optional, Protocol, runtime_checkable
@@ -27,6 +29,46 @@
 ArchiveFn = Callable[[List[Dict[str, Any]]], Awaitable[None]]
 TokenCountFn = Callable[[str], int]
 
+# ── Adaptive scaling constants ────────────────────────────────────────
+# These define how thresholds scale with context_length. They are NOT
+# per-model magic numbers — the formulas produce smooth curves that
+# work across 32K → 2M+ context windows.
+
+_TRIM_CEILING_CHARS = 50_000
+_TRIM_CONTEXT_DIVISOR = 50
+_TRIM_BUDGET_ACTIVATION_RATIO = 0.15
+
+
+def estimate_text_tokens(text: str) -> int:
+    """CJK-aware token estimate for a single text string.
+
+    CJK characters map roughly 1:1 to tokens; Latin text uses the
+    standard ~4 characters per token heuristic.  Shared across the
+    compression pipeline and budget estimator for consistency.
+    """
+    if not text:
+        return 0
+    cjk = sum(
+        1 for ch in text
+        if "\u4e00" <= ch <= "\u9fff" or "\u3000" <= ch <= "\u303f"
+    )
+    latin = len(text) - cjk
+    return max(1, cjk + latin // 4)
+
+
+def adaptive_trim_chars(base: int, context_length: int) -> int:
+    """Compute context-adaptive trim threshold in characters.
+
+    Returns *at least* ``base`` chars, scaling up proportionally to the
+    model's context window so that larger windows tolerate longer tool
+    outputs without unnecessary truncation.
+    """
+    if context_length <= 0:
+        return base
+    context_chars = context_length * 4
+    adaptive = min(_TRIM_CEILING_CHARS, context_chars // _TRIM_CONTEXT_DIVISOR)
+    return max(base, adaptive)
+
 
 @runtime_checkable
 class CompressionStage(Protocol):
@@ -50,14 +92,19 @@ def apply(self, messages: List[Dict[str, Any]], budget: int) -> List[Dict[str, A
 class CompressorConfig:
     """Configuration for the multi-stage compressor.
 
-    Backward-compatible: accepts legacy field names (threshold, keep_tail,
-    max_output_chars) and maps them to new semantics.
+    Accepts legacy field names (threshold, keep_tail, max_output_chars) and
+    maps them to current semantics.  When ``context_length`` is set, trim
+    thresholds are scaled adaptively so that larger context windows tolerate
+    bigger tool outputs without premature truncation.
     """
 
     token_budget: int = 128_000
+    context_length: int = 0
     trim_threshold_chars: int = 2000
     trim_head_ratio: float = 0.25
     trim_tail_ratio: float = 0.1
+    trim_ceiling_chars: int = _TRIM_CEILING_CHARS
+    trim_budget_activation_ratio: float = _TRIM_BUDGET_ACTIVATION_RATIO
     summarize_threshold_messages: int = 16
     summarize_keep_recent: int = 6
     archive_threshold_messages: int = 24
@@ -80,7 +127,7 @@ class CompressorConfig:
     max_output_chars: int = 2000
 
     def __post_init__(self) -> None:
-        """Map legacy fields into new config semantics."""
+        """Map legacy fields and apply adaptive scaling."""
         if self.max_output_chars != 2000 or self.trim_threshold_chars == 2000:
             self.trim_threshold_chars = self.max_output_chars
         if self.threshold != 16 or self.summarize_threshold_messages == 16:
@@ -89,17 +136,27 @@ def __post_init__(self) -> None:
             self.summarize_keep_recent = max(self.keep_tail, 4)
             self.drop_keep_recent = self.keep_tail
 
+        self._base_trim_threshold = self.trim_threshold_chars
+        self._apply_adaptive_scaling()
+
+    def _apply_adaptive_scaling(self) -> None:
+        """Scale thresholds proportionally to context window size."""
+        self.trim_threshold_chars = adaptive_trim_chars(
+            self._base_trim_threshold, self.context_length,
+        )
+
 
 class TrimStage:
     """Stage 1: Truncate oversized tool outputs + dedup identical results (zero LLM cost).
 
-    Three passes (inspired by hermes context_compressor):
+    Three passes:
     1. Dedup: collapse identical tool results (MD5, >dedup_min_chars)
     2. Truncate: head/tail trim for remaining oversized outputs
     3. Strip tool_call arguments over threshold
 
-    Preserves head/tail of long outputs for context.
-    Only targets tool/function/assistant messages — never system.
+    Budget-aware: when context utilization is below ``budget_activation_ratio``
+    only messages exceeding ``ceiling_chars`` are trimmed, preserving full tool
+    output when the context window has plenty of room.
     """
 
     def __init__(
@@ -109,8 +166,12 @@ def __init__(
         head_ratio: float = 0.25,
         tail_ratio: float = 0.1,
         dedup_min_chars: int = 200,
+        ceiling_chars: int = _TRIM_CEILING_CHARS,
+        budget_activation_ratio: float = _TRIM_BUDGET_ACTIVATION_RATIO,
     ) -> None:
         self._max_chars = max_chars
+        self._ceiling_chars = ceiling_chars
+        self._budget_activation_ratio = budget_activation_ratio
         self._head_size = max(100, int(max_chars * head_ratio))
         self._tail_size = max(50, int(max_chars * tail_ratio))
         self._dedup_min = dedup_min_chars
@@ -120,11 +181,16 @@ def name(self) -> str:
         return "trim"
 
     def should_apply(self, messages: List[Dict[str, Any]], token_count: int, budget: int) -> bool:
-        return any(
-            isinstance(msg.get("content"), str) and len(msg["content"]) > self._max_chars
-            for msg in messages
+        target = [
+            msg for msg in messages
             if msg.get("role") in ("tool", "function", "assistant")
-        )
+            and isinstance(msg.get("content"), str)
+        ]
+        if any(len(msg["content"]) > self._ceiling_chars for msg in target):
+            return True
+        if budget > 0 and token_count < budget * self._budget_activation_ratio:
+            return False
+        return any(len(msg["content"]) > self._max_chars for msg in target)
 
     def apply(self, messages: List[Dict[str, Any]], budget: int) -> List[Dict[str, Any]]:
         result = self._dedup_tool_results(messages)
@@ -156,6 +222,7 @@ def _dedup_tool_results(self, messages: List[Dict[str, Any]]) -> List[Dict[str,
 
     def _truncate_outputs(self, messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """Truncate oversized tool/assistant outputs with head+tail preservation."""
+        effective_limit = min(self._max_chars, self._ceiling_chars)
         result: List[Dict[str, Any]] = []
         trimmed_count = 0
         for msg in messages:
@@ -163,7 +230,7 @@ def _truncate_outputs(self, messages: List[Dict[str, Any]]) -> List[Dict[str, An
             role = msg.get("role", "")
             if (
                 isinstance(content, str)
-                and len(content) > self._max_chars
+                and len(content) > effective_limit
                 and role in ("tool", "function", "assistant")
             ):
                 head = content[: self._head_size]
@@ -232,6 +299,71 @@ def _truncate_outputs(self, messages: List[Dict[str, Any]]) -> List[Dict[str, An
 Update all sections as needed. Preserve the same output format."""
 
 
+def _log_archive_result(task: asyncio.Task[None]) -> None:
+    """Callback for archive tasks — log failures instead of silencing them."""
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.warning(
+            "ArchiveStage: background archive failed (%s: %s)",
+            type(exc).__name__, exc,
+        )
+
+
+# ── Deterministic summary helpers ─────────────────────────────────────
+
+_KEY_ARG_NAMES = (
+    "path", "file", "command", "query", "action", "url", "chat_id", "pattern", "text",
+)
+
+
+def _compact_tool_args(args_str: str, limit: int = 120) -> str:
+    """Extract key argument values from tool call JSON arguments."""
+    if not args_str:
+        return ""
+    try:
+        args = json.loads(args_str)
+    except (json.JSONDecodeError, TypeError):
+        return args_str[:limit]
+    if not isinstance(args, dict):
+        return str(args)[:limit]
+    parts: list[str] = []
+    for key in _KEY_ARG_NAMES:
+        if key in args:
+            parts.append(f"{key}={str(args[key])[:60]}")
+    if not parts:
+        for key, val in list(args.items())[:2]:
+            parts.append(f"{key}={str(val)[:40]}")
+    return ", ".join(parts[:3])
+
+
+_KEY_RESULT_FIELDS = (
+    "ok", "error", "path", "kind", "message_id", "resource_id", "id", "exit_code",
+)
+
+
+def _compact_tool_result(content: str, limit: int = 150) -> str:
+    """Extract key information from a tool result for summaries."""
+    if not content or content == "null":
+        return "completed"
+    try:
+        data = json.loads(content)
+        if isinstance(data, dict):
+            parts: list[str] = []
+            for key in _KEY_RESULT_FIELDS:
+                if key in data:
+                    parts.append(f"{key}={str(data[key])[:60]}")
+            if parts:
+                return "; ".join(parts[:4])
+    except (json.JSONDecodeError, TypeError):
+        pass
+    first_line = content.split("\n", 1)[0].strip()
+    if first_line:
+        return first_line[:limit]
+    return content[:limit]
+
+
 class SummarizeStage:
     """Stage 2: LLM-based summarization of middle turns.
 
@@ -363,7 +495,7 @@ def _format_turns_for_summary(messages: List[Dict[str, Any]]) -> str:
         for i, msg in enumerate(messages):
             role = msg.get("role", "unknown")
             content = str(msg.get("content", ""))
-            tool_calls = msg.get("tool_calls", [])
+            tool_calls = msg.get("tool_calls") or []
             if role == "assistant" and tool_calls:
                 tool_names = [tc.get("function", {}).get("name", "?") for tc in tool_calls]
                 lines.append(f"[Turn {i+1}] ASSISTANT: called tools: {', '.join(tool_names)}")
@@ -378,24 +510,38 @@ def _format_turns_for_summary(messages: List[Dict[str, Any]]) -> str:
 
     @staticmethod
     def _deterministic_summary(middle: List[Dict[str, Any]]) -> str:
-        """Zero-LLM-cost summary as fallback."""
+        """Zero-LLM-cost summary as fallback.
+
+        Preserves tool names with key arguments, structured fields from
+        tool results (paths, error codes, resource ids), and the full
+        breadth of user messages so that the agent retains enough context
+        to continue its task after compression.
+        """
         summary_lines: List[str] = []
         for msg in middle:
             role = msg.get("role", "")
-            content = str(msg.get("content", ""))[:80]
-            tool_calls = msg.get("tool_calls", [])
+            content = str(msg.get("content", ""))
+            tool_calls = msg.get("tool_calls") or []
             if role == "assistant" and tool_calls:
-                tool_names = [tc.get("function", {}).get("name", "?") for tc in tool_calls]
-                summary_lines.append(f"[assistant] called: {', '.join(tool_names)}")
+                parts = []
+                for tc in tool_calls:
+                    func = tc.get("function", {})
+                    name = func.get("name", "?")
+                    args_summary = _compact_tool_args(func.get("arguments", ""))
+                    parts.append(f"{name}({args_summary})" if args_summary else name)
+                summary_lines.append(f"[assistant] called: {', '.join(parts)}")
+                if content:
+                    summary_lines.append(f"  → {content[:120]}")
             elif role in ("tool", "function"):
-                summary_lines.append("[tool_result] executed")
+                excerpt = _compact_tool_result(content)
+                summary_lines.append(f"[tool] {excerpt}")
             elif role == "user":
-                summary_lines.append(f"[user] {content[:50]}...")
+                summary_lines.append(f"[user] {content[:200]}")
             else:
-                summary_lines.append(f"[{role}] {content[:50]}...")
+                summary_lines.append(f"[{role}] {content[:120]}")
         return (
             f"## Historical Context ({len(middle)} messages)\n"
-            + "\n".join(summary_lines[-20:])
+            + "\n".join(summary_lines[-30:])
         )
 
     @staticmethod
@@ -419,7 +565,7 @@ def _sanitize_tool_pairs(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]
         """Remove orphaned tool results and strip orphaned tool_calls."""
         available_call_ids: set[str] = set()
         for msg in messages:
-            for tc in msg.get("tool_calls", []):
+            for tc in msg.get("tool_calls") or []:
                 call_id = tc.get("id", "") or tc.get("call_id", "")
                 if call_id:
                     available_call_ids.add(call_id)
@@ -489,7 +635,8 @@ def apply(self, messages: List[Dict[str, Any]], budget: int) -> List[Dict[str, A
             try:
                 loop = asyncio.get_event_loop()
                 if loop.is_running():
-                    asyncio.create_task(self._archive_fn(archived))
+                    task = asyncio.create_task(self._archive_fn(archived))
+                    task.add_done_callback(_log_archive_result)
                 else:
                     loop.run_until_complete(self._archive_fn(archived))
             except Exception as exc:
@@ -594,6 +741,41 @@ def last_trace(self) -> CompressionTrace:
         """Return the most recent compression trace."""
         return self._last_trace
 
+    def reconfigure(self, *, token_budget: int = 0, context_length: int = 0) -> None:
+        """Update runtime budget/context and rebuild affected stages.
+
+        Only TrimStage is rebuilt — SummarizeStage and other stateful stages
+        retain their iterative summary history and compression counters so
+        that a hot-reload mid-session does not break summary continuity.
+        """
+        changed = False
+        if token_budget > 0 and token_budget != self._config.token_budget:
+            self._config.token_budget = token_budget
+            changed = True
+        if context_length > 0 and context_length != self._config.context_length:
+            self._config.context_length = context_length
+            self._config._apply_adaptive_scaling()
+            changed = True
+        if changed:
+            new_trim = TrimStage(
+                max_chars=self._config.trim_threshold_chars,
+                head_ratio=self._config.trim_head_ratio,
+                tail_ratio=self._config.trim_tail_ratio,
+                dedup_min_chars=self._config.dedup_min_chars,
+                ceiling_chars=self._config.trim_ceiling_chars,
+                budget_activation_ratio=self._config.trim_budget_activation_ratio,
+            )
+            self._stages = [
+                new_trim if stage.name == "trim" else stage
+                for stage in self._stages
+            ]
+            logger.debug(
+                "ContextCompressor reconfigured: budget=%d, context_length=%d, trim_chars=%d",
+                self._config.token_budget,
+                self._config.context_length,
+                self._config.trim_threshold_chars,
+            )
+
     def _build_stages(self, config: CompressorConfig) -> List[CompressionStage]:
         """Build stage chain from config."""
         stage_map: Dict[str, CompressionStage] = {
@@ -602,6 +784,8 @@ def _build_stages(self, config: CompressorConfig) -> List[CompressionStage]:
                 head_ratio=config.trim_head_ratio,
                 tail_ratio=config.trim_tail_ratio,
                 dedup_min_chars=config.dedup_min_chars,
+                ceiling_chars=config.trim_ceiling_chars,
+                budget_activation_ratio=config.trim_budget_activation_ratio,
             ),
             "summarize": SummarizeStage(
                 threshold_messages=config.summarize_threshold_messages,
@@ -727,18 +911,30 @@ def _build_trace(
         )
 
     def _count_tokens(self, messages: List[Dict[str, Any]]) -> int:
-        """Count tokens using external tokenizer if available, else estimate."""
+        """Count tokens using external tokenizer if available, else estimate.
+
+        Always handles multimodal content parts and images regardless
+        of whether a custom ``token_count_fn`` is set.
+        """
+        _IMAGE_TOKEN_ESTIMATE = 1600
         if self._config.token_count_fn is not None:
+            fn = self._config.token_count_fn
             total = 0
             for msg in messages:
                 content = msg.get("content", "")
                 if isinstance(content, str):
-                    total += self._config.token_count_fn(content)
-                tool_calls = msg.get("tool_calls", [])
-                for tc in tool_calls:
+                    total += fn(content)
+                elif isinstance(content, list):
+                    for part in content:
+                        if isinstance(part, dict):
+                            if part.get("type") == "text":
+                                total += fn(part.get("text", ""))
+                            elif part.get("type") in ("image_url", "input_image", "image"):
+                                total += _IMAGE_TOKEN_ESTIMATE
+                for tc in msg.get("tool_calls") or []:
                     args = tc.get("function", {}).get("arguments", "")
                     if isinstance(args, str):
-                        total += self._config.token_count_fn(args)
+                        total += fn(args)
             return total
         return self._estimate_tokens(messages)
 
@@ -835,33 +1031,32 @@ def preflight_check(
 
     @staticmethod
     def _estimate_tokens(messages: List[Dict[str, Any]]) -> int:
-        """Token estimation: ~4 chars/token for text, ~1600 tokens per image part.
+        """CJK-aware token estimation with multimodal support.
 
-        Multimodal-aware: detects image_url and input_image content parts
-        and adds a flat token estimate per image (inspired by hermes
-        _IMAGE_TOKEN_ESTIMATE = 1600).
+        Uses ``estimate_text_tokens`` for consistent CJK-aware counting
+        and adds ~1600 tokens per image part.
         """
         _IMAGE_TOKEN_ESTIMATE = 1600
-        total_chars = 0
+        total_tokens = 0
         image_count = 0
 
         for msg in messages:
             content = msg.get("content", "")
             if isinstance(content, str):
-                total_chars += len(content)
+                total_tokens += estimate_text_tokens(content)
             elif isinstance(content, list):
                 for part in content:
                     if not isinstance(part, dict):
                         continue
                     part_type = part.get("type", "")
                     if part_type == "text":
-                        total_chars += len(part.get("text", ""))
+                        total_tokens += estimate_text_tokens(part.get("text", ""))
                     elif part_type in ("image_url", "input_image", "image"):
                         image_count += 1
 
-            for tc in msg.get("tool_calls", []):
+            for tc in msg.get("tool_calls") or []:
                 args = tc.get("function", {}).get("arguments", "")
                 if isinstance(args, str):
-                    total_chars += len(args)
+                    total_tokens += estimate_text_tokens(args)
 
-        return (total_chars // 4) + (image_count * _IMAGE_TOKEN_ESTIMATE)
+        return total_tokens + (image_count * _IMAGE_TOKEN_ESTIMATE)
diff --git a/src/leapflow/engine/context_control.py b/src/leapflow/engine/context_control.py
index dfe964d..732c869 100644
--- a/src/leapflow/engine/context_control.py
+++ b/src/leapflow/engine/context_control.py
@@ -12,6 +12,8 @@
 from pathlib import Path
 from typing import Any, Dict, List, Protocol, Sequence, runtime_checkable
 
+from leapflow.engine.context_compressor import estimate_text_tokens as _estimate_text_tokens
+
 logger = logging.getLogger(__name__)
 
 _IMAGE_TOKEN_ESTIMATE = 1600
@@ -144,13 +146,7 @@ def _estimate_tool_calls(self, tool_calls: Any) -> int:
 
     @staticmethod
     def _estimate_text(text: str) -> int:
-        if not text:
-            return 0
-        cjk_count = sum(
-            1 for ch in text if "\u4e00" <= ch <= "\u9fff" or "\u3000" <= ch <= "\u303f"
-        )
-        latin_chars = len(text) - cjk_count
-        return max(1, cjk_count + latin_chars // 4)
+        return _estimate_text_tokens(text)
 
 
 class ContextWindowController:
@@ -241,17 +237,40 @@ def _tail_preserving_drop(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]
         return head + [notice] + tail
 
 
+_EVIDENCE_CEILING_CHARS = 8_000
+_EVIDENCE_CONTEXT_DIVISOR = 32
+
+
 class ToolEvidenceBuilder:
-    """Convert verbose tool outputs into compact evidence for LLM replay."""
+    """Convert verbose tool outputs into compact evidence for LLM replay.
 
-    def __init__(self, *, max_content_chars: int = 1200, max_items: int = 40) -> None:
-        self._max_content_chars = max(200, max_content_chars)
+    When ``context_length`` is provided, ``max_content_chars`` is raised
+    proportionally so that larger context windows retain richer tool evidence.
+    """
+
+    def __init__(
+        self,
+        *,
+        max_content_chars: int = 1200,
+        max_items: int = 40,
+        context_length: int = 0,
+    ) -> None:
+        if context_length > 0:
+            adaptive = max(
+                max_content_chars,
+                min(_EVIDENCE_CEILING_CHARS, context_length // _EVIDENCE_CONTEXT_DIVISOR),
+            )
+            self._max_content_chars = max(200, adaptive)
+        else:
+            self._max_content_chars = max(200, max_content_chars)
         self._max_items = max(5, max_items)
 
     def build(self, tool_name: str, arguments: Dict[str, Any] | None, result: Any) -> Any:
         """Return a compact, JSON-serializable result preserving task evidence."""
         if not isinstance(result, dict):
             return self._compact_value(result)
+        if tool_name == "platform_connect":
+            return self._app_connector_evidence(result)
         if result.get("ok") is False:
             return self._compact_error(result)
         if tool_name in {"file_read", "gp_file_read"}:
@@ -306,6 +325,56 @@ def _compact_error(self, result: Dict[str, Any]) -> Dict[str, Any]:
             "error": self._head_tail(str(result.get("error", "unknown error")), self._max_content_chars),
         }
 
+    def _app_connector_evidence(self, result: Dict[str, Any]) -> Dict[str, Any]:
+        evidence: Dict[str, Any] = {
+            "ok": bool(result.get("ok", True)),
+            "kind": "app_connector_evidence",
+        }
+        for key in (
+            "platform",
+            "stage",
+            "onboarding_state",
+            "recovery_hint",
+            "next_steps",
+            "error",
+            "status",
+            "connected",
+        ):
+            if key in result:
+                evidence[key] = self._compact_value(result[key])
+        if isinstance(result.get("preflight_result"), dict):
+            evidence["preflight_result"] = self._app_preflight_evidence(result["preflight_result"])
+        if "required_fields" in result:
+            evidence["required_fields"] = self._compact_value(result["required_fields"])
+        return evidence
+
+    def _app_check_evidence(self, checks: List[Any]) -> List[Dict[str, Any]]:
+        return [
+            {
+                compact_key: check.get(compact_key)
+                for compact_key in ("key", "kind", "status", "failure_code", "requires_approval", "auto_run")
+                if isinstance(check, dict) and compact_key in check
+            }
+            for check in checks[: self._max_items]
+        ]
+
+    def _app_preflight_evidence(self, preflight: Dict[str, Any]) -> Dict[str, Any]:
+        evidence: Dict[str, Any] = {}
+        for key in ("ready", "stage", "backend_kind", "recoverable", "detail", "recovery_hint", "next_steps"):
+            if key in preflight:
+                evidence[key] = self._compact_value(preflight[key])
+        checks = preflight.get("checks")
+        if isinstance(checks, list):
+            evidence["checks"] = self._app_check_evidence(checks)
+        metadata = preflight.get("metadata")
+        if isinstance(metadata, dict):
+            evidence["metadata"] = {
+                key: self._compact_value(metadata[key])
+                for key in ("binary", "binary_path", "profile", "identity", "auth_status")
+                if key in metadata
+            }
+        return evidence
+
     def _compact_mapping(self, result: Dict[str, Any]) -> Dict[str, Any]:
         compact: Dict[str, Any] = {}
         for key, value in result.items():
diff --git a/src/leapflow/engine/engine.py b/src/leapflow/engine/engine.py
index b50ff2d..2299935 100644
--- a/src/leapflow/engine/engine.py
+++ b/src/leapflow/engine/engine.py
@@ -141,7 +141,7 @@ def _tool_args_metadata(
     metadata["tool_name"] = tool_name
     metadata["normalized_tool_name"] = tool_name
     if original_name != tool_name:
-        metadata["alias"] = original_name
+        metadata["resolved_from"] = original_name
     for key in ("command", "cmd", "path", "pattern", "query", "url"):
         value = args.get(key)
         if value:
@@ -178,6 +178,14 @@ def _tool_result_metadata(
                     value,
                     limit=_TOOL_RESULT_PREVIEW_LIMIT,
                 )
+        # App Connector recovery metadata for TUI transparency
+        recovery_hint = result.get("recovery_hint")
+        if recovery_hint:
+            metadata["recovery_hint"] = _single_line_preview(recovery_hint, limit=_TOOL_RESULT_PREVIEW_LIMIT)
+        onboarding_state = result.get("onboarding_state")
+        if isinstance(onboarding_state, dict) and onboarding_state.get("stage"):
+            metadata["onboarding_stage"] = str(onboarding_state["stage"])
+            metadata["onboarding_platform"] = str(onboarding_state.get("platform_id") or "")
         if not any(key.endswith("_preview") for key in metadata):
             metadata["result_preview"] = _single_line_preview(
                 result,
@@ -198,6 +206,22 @@ def _is_retryable_unknown_tool_result(result: Any) -> bool:
     )
 
 
+def _platform_action_fingerprint(tool_name: str, arguments: Mapping[str, Any]) -> str | None:
+    """Return a dedup fingerprint for platform_action calls; None for all other tools.
+
+    Used to prevent duplicate side-effect actions (send, write) within one turn.
+    Two calls are considered duplicates when platform, action name, and payload
+    are all identical.
+    """
+    if tool_name != "platform_action":
+        return None
+    platform = str(arguments.get("platform") or "")
+    action = str(arguments.get("action") or "")
+    payload = arguments.get("payload") or {}
+    payload_key = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    return f"{platform}:{action}:{payload_key}"
+
+
 def _unknown_tool_retry_prompt(result: Dict[str, Any]) -> str:
     """Build a compact structured correction prompt for a bad tool name."""
     suggestions = result.get("suggestions") or []
@@ -211,10 +235,112 @@ def _unknown_tool_retry_prompt(result: Dict[str, Any]) -> str:
         f"({result.get('resolution_reason', 'no match')}). "
         f"Suggested canonical tools: {suggestions_text}. "
         f"Available tools include: {available_text}. "
-        "Retry once using an exact canonical tool name and valid arguments, or answer without a tool if no tool fits."
+        "Retry once using an exact canonical tool name from the available list and valid arguments. "
+        "Do not invent tool names, use aliases, or infer a tool from argument shape; answer without a tool if no exact tool fits."
     )
 
 
+def _last_tool_failures_recovery_message(messages: List[Dict[str, Any]]) -> str:
+    """Build a user-facing message from the last consecutive tool failures.
+
+    Called when the loop exits with no content due to hitting
+    max_consecutive_tool_failures.  Returns "" when no useful failure context
+    is available in the recent message history.
+    """
+    failures: List[Dict[str, Any]] = []
+    for msg in reversed(messages[-24:]):
+        content = str(msg.get("content") or "").strip()
+        if not content:
+            continue
+        # Strip "Tool result (name):\n" prefix from text-mode tool messages
+        if content.startswith("Tool result (") and ":\n" in content:
+            content = content.split(":\n", 1)[1].strip()
+        try:
+            payload = json.loads(content)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(payload, dict) or payload.get("ok", True):
+            continue
+        failures.append(payload)
+        if len(failures) >= 3:
+            break
+
+    if not failures:
+        return ""
+
+    last = failures[0]
+    failure_code = str(last.get("failure_code") or "")
+    error = str(last.get("error") or "")
+    recovery_hint = str(last.get("recovery_hint") or "")
+    available_actions: List[str] = list(last.get("available_action_names") or [])
+
+    lines: List[str] = []
+    if failure_code == "unknown_platform_action":
+        platform = str(last.get("platform") or "")
+        action = str(last.get("requested_action") or "")
+        lines.append(f"`{platform}.{action}` is not a registered platform action.")
+        if available_actions:
+            actions_str = ", ".join(f"`{a}`" for a in available_actions[:10])
+            lines.append(f"Registered actions for {platform}: {actions_str}.")
+    elif failure_code == "wrong_action_namespace":
+        action = str(last.get("requested_action") or "")
+        lines.append(
+            f"`{action}` is a platform management action — "
+            "use `platform_connect` (not `platform_action`) for this."
+        )
+    elif failure_code == "unknown_platform":
+        lines.append(error)
+        platforms: List[str] = list(last.get("available_platforms") or [])
+        if platforms:
+            lines.append(f"Available platforms: {', '.join(platforms)}.")
+    elif "Missing required fields" in error:
+        lines.append(f"Action parameter incomplete: {error}. Please provide the missing field(s) and retry.")
+    elif error:
+        lines.append(f"Action failed: {error}")
+
+    if recovery_hint and not any(recovery_hint[:50] in line for line in lines):
+        lines.append(f"Hint: {recovery_hint}")
+
+    if len(failures) > 1:
+        lines.append(f"({len(failures)} consecutive tool failures in this turn)")
+
+    return "\n".join(lines) if lines else ""
+
+
+def _app_onboarding_recovery_message(messages: List[Dict[str, Any]]) -> str:
+    """Build a useful final answer from recent App Connector recovery state."""
+    for message in reversed(messages):
+        content = str(message.get("content") or "").strip()
+        if not content:
+            continue
+        if content.startswith("Tool result (") and ":\n" in content:
+            content = content.split(":\n", 1)[1].strip()
+        try:
+            payload = json.loads(content)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        state = payload.get("onboarding_state")
+        if not isinstance(state, dict):
+            continue
+        platform = str(state.get("platform") or state.get("platform_id") or "the app")
+        stage = str(state.get("stage") or "pending")
+        hint = str(payload.get("recovery_hint") or state.get("last_error") or "")
+        steps = payload.get("next_steps") or state.get("next_actions") or []
+        lines = [
+            f"App onboarding is paused for {platform} at stage `{stage}`.",
+        ]
+        if hint:
+            lines.append(f"Reason: {hint}")
+        if isinstance(steps, list) and steps:
+            lines.append("Next steps:")
+            lines.extend(f"- {step}" for step in steps[:4])
+        lines.append("After completing the missing step, continue the same onboarding flow; LeapFlow will reuse the pending App Connector state.")
+        return "\n".join(lines)
+    return ""
+
+
 def _estimate_text_tokens(text: str) -> int:
     """Approximate token count for status display when provider usage is absent."""
     if not text:
@@ -411,6 +537,11 @@ def render(self) -> str:
                 "- Treat relative project paths as relative to the workspace root; never infer `.` "
                 "as the project root when a workspace root is provided."
             ),
+            (
+                "- LeapFlow config is not stored at `<workspace>/.leapflow/config.json`; "
+                "do not probe that path. Runtime config is loaded from `~/.leapflow/.env` "
+                "with optional project override `./.env` only when that file exists."
+            ),
             (
                 "- Preserve this task contract across summarization, compression, "
                 "tool loops, and memory retrieval."
@@ -547,8 +678,10 @@ def __init__(
                 rate_limit_base_delay=settings.error_rate_limit_base_delay,
             )
         )
+        ctx_len = settings.llm_context_length
         self._compressor = ContextCompressor(CompressorConfig(
-            token_budget=max(1, int(settings.llm_context_length * settings.context_hard_limit_ratio)),
+            token_budget=max(1, int(ctx_len * settings.context_hard_limit_ratio)),
+            context_length=ctx_len,
             threshold=settings.compress_threshold,
             keep_tail=settings.compress_keep_tail,
             max_output_chars=settings.max_tool_output_chars,
@@ -561,6 +694,7 @@ def __init__(
         self._context_governance_controller = ContextGovernanceController(
             evidence_builder=ToolEvidenceBuilder(
                 max_content_chars=settings.tool_evidence_max_chars,
+                context_length=ctx_len,
             ),
             repeated_read_limit=settings.repeated_read_limit,
             convergence_round=settings.long_task_convergence_round,
@@ -635,8 +769,10 @@ def reconfigure_runtime(
         self._llm = llm
         self._vlm = vlm
         self._classifier = classifier
+        ctx_len = settings.llm_context_length
         self._compressor = ContextCompressor(CompressorConfig(
-            token_budget=max(1, int(settings.llm_context_length * settings.context_hard_limit_ratio)),
+            token_budget=max(1, int(ctx_len * settings.context_hard_limit_ratio)),
+            context_length=ctx_len,
             threshold=settings.compress_threshold,
             keep_tail=settings.compress_keep_tail,
             max_output_chars=settings.max_tool_output_chars,
@@ -649,6 +785,7 @@ def reconfigure_runtime(
         self._context_governance_controller = ContextGovernanceController(
             evidence_builder=ToolEvidenceBuilder(
                 max_content_chars=settings.tool_evidence_max_chars,
+                context_length=ctx_len,
             ),
             repeated_read_limit=settings.repeated_read_limit,
             convergence_round=settings.long_task_convergence_round,
@@ -1060,8 +1197,10 @@ async def _assemble_unified_prompt(
         elif plan.memory in {MemoryDisclosure.QUERY_RETRIEVAL, MemoryDisclosure.TASK_RETRIEVAL}:
             memory_context = await self._prefetch_and_freeze_memory(user_text)
         skill_section = self._build_skill_section(include_skills=plan.level != DisclosureLevel.LIGHT)
+        app_connector_section = self._build_app_connector_section()
         system = UNIFIED_SYSTEM_TEMPLATE.format(
             tool_catalog=tool_catalog,
+            app_connector_section=app_connector_section,
             skill_section=skill_section,
             memory_context=memory_context,
         )
@@ -1323,6 +1462,16 @@ async def run_stream(
         async for chunk in self._unified_tool_loop_stream(user_text, enable_thinking=enable_thinking):
             yield chunk
 
+    def _build_app_connector_section(self) -> str:
+        """Return prompt-time app connector capabilities without classifying the user turn."""
+        try:
+            from leapflow.tools.gateway_tool import build_app_connector_prompt_section
+
+            return build_app_connector_prompt_section()
+        except Exception:
+            logger.debug("app connector prompt section unavailable", exc_info=True)
+            return ""
+
     # ── Complex Task Handling (DAG path) ─────────────────────────────
 
     async def _handle_complex_task(self, user_goal: str) -> str:
@@ -1931,7 +2080,16 @@ async def _unified_tool_loop(
 
         logger.info("turn_usage: %s", self._usage_tracker.format_log_line())
 
-        return content if content else (fatal_error or "I've reached my processing limit.")
+        if content:
+            return content
+        if fatal_error:
+            return fatal_error
+        # Derive a recovery message from the last platform_connect failure if present
+        return (
+            _app_onboarding_recovery_message(messages)
+            or _last_tool_failures_recovery_message(messages)
+            or "I've reached my processing limit."
+        )
 
     async def _post_turn_review(
         self, messages: List[Dict[str, Any]], final_content: str
@@ -2339,7 +2497,8 @@ async def _unified_tool_loop_stream(
             if tool_call is None:
                 trace.record(ExecutionMode.COMPLETE)
                 if not content:
-                    yield StreamEvent(type="final", content="I processed your request but have no additional output.")
+                    fallback = _app_onboarding_recovery_message(messages)
+                    yield StreamEvent(type="final", content=fallback or "I processed your request but have no additional output.")
                 else:
                     yield StreamEvent(type="final", content=content)
                 return
@@ -2427,7 +2586,16 @@ async def _unified_tool_loop_stream(
 
         logger.info("turn_usage: %s", self._usage_tracker.format_log_line())
 
-        yield StreamEvent(type="final", content=content if content else (fatal_error or "I've reached my processing limit."))
+        if content:
+            yield StreamEvent(type="final", content=content)
+        else:
+            fallback = (
+                _app_onboarding_recovery_message(messages)
+                or _last_tool_failures_recovery_message(messages)
+                or fatal_error
+                or "I've reached my processing limit."
+            )
+            yield StreamEvent(type="final", content=fallback)
 
 
     # ── Unified Loop Helpers ───────────────────────────────────────────────
@@ -2476,6 +2644,48 @@ async def _execute_tools_concurrent(
         result_budget = self._effective_tool_result_budget()
         executed: list[Dict[str, Any]] = []
         original_names_by_id = {str(tc.id): str(tc.name) for tc in native_calls}
+
+        # Idempotency guard: skip duplicate platform_action calls within one turn.
+        # Prevents the model from accidentally repeating a side-effect action
+        # (e.g. im.send_message) when it copies the "first-try-failed → retry"
+        # pattern from a previous turn into the current turn's tool_calls list.
+        seen_action_fps: set[str] = set()
+        deduped: list = []
+        for tc in native_calls:
+            fp = _platform_action_fingerprint(str(tc.name), dict(tc.arguments or {}))
+            if fp is not None and fp in seen_action_fps:
+                action_name = str((tc.arguments or {}).get("action") or tc.name)
+                skip_result: Dict[str, Any] = {
+                    "ok": False,
+                    "error": "idempotency_guard: duplicate platform_action skipped",
+                    "reason": (
+                        f"'{action_name}' with identical payload was already queued "
+                        "in this turn; LeapFlow prevents duplicate side-effects."
+                    ),
+                    "retryable": False,
+                }
+                messages.append({
+                    "role": "tool",
+                    "tool_call_id": tc.id,
+                    "content": json.dumps(skip_result, ensure_ascii=False),
+                })
+                executed.append({
+                    "id": tc.id,
+                    "name": "platform_action",
+                    "original_tool_name": "platform_action",
+                    "arguments": dict(tc.arguments or {}),
+                    "result": skip_result,
+                })
+                logger.info(
+                    "idempotency_guard: skipped duplicate platform_action tc_id=%s action=%s",
+                    tc.id, action_name,
+                )
+                continue
+            if fp is not None:
+                seen_action_fps.add(fp)
+            deduped.append(tc)
+        native_calls = deduped
+
         tc_wrappers = [
             ConcurrentToolCall(
                 id=tc.id,
diff --git a/src/leapflow/gateway/action_packs/__init__.py b/src/leapflow/gateway/action_packs/__init__.py
new file mode 100644
index 0000000..21c1998
--- /dev/null
+++ b/src/leapflow/gateway/action_packs/__init__.py
@@ -0,0 +1 @@
+"""Built-in platform action packs."""
diff --git a/src/leapflow/gateway/action_packs/feishu.py b/src/leapflow/gateway/action_packs/feishu.py
new file mode 100644
index 0000000..a57dd2d
--- /dev/null
+++ b/src/leapflow/gateway/action_packs/feishu.py
@@ -0,0 +1,24 @@
+"""Feishu/Lark action pack — loaded from feishu.yaml.
+
+All action definitions live in feishu.yaml next to this file.
+Add new Feishu capabilities there without changing Python code.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from leapflow.gateway.connectors.action_registry import ActionRegistry
+from leapflow.gateway.connectors.protocol import ActionSpec
+
+_YAML_PATH = Path(__file__).parent / "feishu.yaml"
+_registry = ActionRegistry.from_yaml(_YAML_PATH)
+
+# ACTION_SPECS is the canonical export consumed by ActionRegistry.from_module().
+ACTION_SPECS: dict[str, ActionSpec] = dict(_registry.all())
+# Legacy alias kept for any direct imports that reference FEISHU_ACTION_SPECS.
+FEISHU_ACTION_SPECS = ACTION_SPECS
+
+
+def get_action_spec(action: str) -> ActionSpec | None:
+    """Return a Feishu action spec by domain.operation name."""
+    return _registry.get(action)
diff --git a/src/leapflow/gateway/action_packs/feishu.yaml b/src/leapflow/gateway/action_packs/feishu.yaml
new file mode 100644
index 0000000..223f772
--- /dev/null
+++ b/src/leapflow/gateway/action_packs/feishu.yaml
@@ -0,0 +1,321 @@
+# Feishu/Lark action pack
+#
+# Each entry under 'actions:' maps to an ActionSpec.  To add a new capability,
+# append an entry here — no Python code change required.
+#
+# Fields:
+#   effect:        read | send | write | execute
+#   risk_level:    low | medium | high
+#   output_policy: raw | summary
+#   schema:        JSON Schema subset (required[] + properties{})
+#   backend.argv:  CLI argument template; {placeholder} tokens are replaced from payload
+#   backend.dry_run_argv:  optional dry-run variant (adds --dry-run flag)
+#
+# Run 'lark-cli <domain> +<cmd> --help' to verify argv flags match the installed
+# CLI version before adding or modifying entries.
+
+version: "1"
+platform: feishu
+
+actions:
+
+  # ── IM: Messaging ─────────────────────────────────────────────────────────
+
+  im.send_message:
+    description: >-
+      Send a text message to a Feishu/Lark chat.
+      Requires chat_id (oc_xxx format); use im.search_chats to resolve a
+      group name to chat_id first.
+    effect: send
+    risk_level: high
+    output_policy: summary
+    schema:
+      required: [chat_id, text]
+      properties:
+        chat_id:
+          type: string
+          description: "Target chat ID (oc_xxx format)."
+        text:
+          type: string
+          description: "Message text content."
+        thread_id:
+          type: string
+          description: "Optional thread ID for replies."
+    backend:
+      kind: cli
+      argv:
+        - im
+        - +messages-send
+        - --chat-id
+        - "{chat_id}"
+        - --text
+        - "{text}"
+      dry_run_argv:
+        - im
+        - +messages-send
+        - --chat-id
+        - "{chat_id}"
+        - --text
+        - "{text}"
+        - --dry-run
+      approval_summary: >-
+        Send a Feishu message to chat {chat_id} as {identity}
+        using {binary} profile {profile}.
+      next_steps:
+        - "Verify the returned message_id/resource_id if the caller needs delivery tracking."
+        - "If sending fails, confirm chat_id and bot/user permissions in the selected Feishu tenant."
+        - "Run lark-cli auth status --json to verify the current profile remains authorized."
+      timeout_s: 30
+
+  im.list_chats:
+    description: >-
+      List Feishu/Lark chats the current user or bot is a member of.
+      Returns chat_id and name for each chat.
+      Use to discover chat_id values when only a group name is known.
+    effect: read
+    risk_level: low
+    output_policy: raw
+    schema:
+      properties:
+        page_size:
+          type: integer
+          description: "Max results to return (1-100, default 20)."
+    backend:
+      kind: cli
+      argv:
+        - im
+        - +chat-list
+      timeout_s: 30
+
+  im.search_chats:
+    description: >-
+      Search Feishu/Lark group chats by name or keyword.
+      Returns matching chats with chat_id and name.
+      Preferred over im.list_chats when you know the group name.
+    effect: read
+    risk_level: low
+    output_policy: raw
+    schema:
+      required: [query]
+      properties:
+        query:
+          type: string
+          description: "Search keyword — typically the group name or a partial name."
+        page_size:
+          type: integer
+          description: "Max results to return (1-100, default 20)."
+    backend:
+      kind: cli
+      argv:
+        - im
+        - +chat-search
+        - --query
+        - "{query}"
+      timeout_s: 30
+
+  # ── Docs ───────────────────────────────────────────────────────────────────
+
+  docs.create_markdown:
+    description: "Create a Feishu/Lark document from markdown content."
+    effect: write
+    risk_level: medium
+    output_policy: summary
+    schema:
+      required: [title, markdown]
+      properties:
+        title:
+          type: string
+          description: "Document title."
+        markdown:
+          type: string
+          description: "Document body in Markdown format."
+        folder_token:
+          type: string
+          description: "Optional destination folder token."
+    backend:
+      kind: cli
+      argv:
+        - docs
+        - +create
+        - --title
+        - "{title}"
+        - --markdown
+        - "{markdown}"
+      dry_run_argv:
+        - docs
+        - +create
+        - --title
+        - "{title}"
+        - --markdown
+        - "{markdown}"
+        - --dry-run
+      timeout_s: 60
+
+  # ── Calendar ───────────────────────────────────────────────────────────────
+
+  calendar.create_event:
+    description: "Create a calendar event."
+    effect: write
+    risk_level: high
+    output_policy: summary
+    schema:
+      required: [summary, start_time, end_time]
+      properties:
+        summary:
+          type: string
+          description: "Event title."
+        start_time:
+          type: string
+          description: "Start time in ISO 8601 format (e.g. 2026-07-14T10:00:00+08:00)."
+        end_time:
+          type: string
+          description: "End time in ISO 8601 format."
+        attendees:
+          type: string
+          description: "Comma-separated attendee IDs or emails."
+    backend:
+      kind: cli
+      argv:
+        - calendar
+        - +events-create
+        - --summary
+        - "{summary}"
+        - --start-time
+        - "{start_time}"
+        - --end-time
+        - "{end_time}"
+      dry_run_argv:
+        - calendar
+        - +events-create
+        - --summary
+        - "{summary}"
+        - --start-time
+        - "{start_time}"
+        - --end-time
+        - "{end_time}"
+        - --dry-run
+      timeout_s: 45
+
+  # ── Drive ──────────────────────────────────────────────────────────────────
+
+  drive.search:
+    description: "Search Feishu/Lark Drive resources."
+    effect: read
+    risk_level: medium
+    output_policy: summary
+    schema:
+      required: [query]
+      properties:
+        query:
+          type: string
+          description: "Search keyword."
+        limit:
+          type: integer
+          description: "Max results to return."
+    backend:
+      kind: cli
+      argv:
+        - drive
+        - +search
+        - --query
+        - "{query}"
+      timeout_s: 30
+
+  # ── Sheets ─────────────────────────────────────────────────────────────────
+
+  sheets.append_row:
+    description: "Append one row to a Feishu/Lark sheet."
+    effect: write
+    risk_level: medium
+    output_policy: summary
+    schema:
+      required: [spreadsheet_token, sheet_id, values]
+      properties:
+        spreadsheet_token:
+          type: string
+          description: "Spreadsheet token."
+        sheet_id:
+          type: string
+          description: "Target sheet ID within the spreadsheet."
+        values:
+          type: array
+          description: "Row values as a JSON array."
+    backend:
+      kind: cli
+      argv:
+        - sheets
+        - +append-row
+        - --spreadsheet-token
+        - "{spreadsheet_token}"
+        - --sheet-id
+        - "{sheet_id}"
+        - --values
+        - "{values}"
+      dry_run_argv:
+        - sheets
+        - +append-row
+        - --spreadsheet-token
+        - "{spreadsheet_token}"
+        - --sheet-id
+        - "{sheet_id}"
+        - --values
+        - "{values}"
+        - --dry-run
+      timeout_s: 45
+
+  # ── Mail ───────────────────────────────────────────────────────────────────
+
+  mail.search_unread:
+    description: "Search unread Feishu/Lark mail."
+    effect: read
+    risk_level: high
+    output_policy: summary
+    schema:
+      properties:
+        query:
+          type: string
+          description: "Optional search keyword."
+        limit:
+          type: integer
+          description: "Max results to return."
+    backend:
+      kind: cli
+      argv:
+        - mail
+        - +search
+        - --unread
+      timeout_s: 30
+
+  # ── Task ───────────────────────────────────────────────────────────────────
+
+  task.create:
+    description: "Create a Feishu/Lark task."
+    effect: write
+    risk_level: medium
+    output_policy: summary
+    schema:
+      required: [title]
+      properties:
+        title:
+          type: string
+          description: "Task title."
+        description:
+          type: string
+          description: "Optional task description."
+        due_time:
+          type: string
+          description: "Optional due time in ISO 8601 format."
+    backend:
+      kind: cli
+      argv:
+        - task
+        - +create
+        - --title
+        - "{title}"
+      dry_run_argv:
+        - task
+        - +create
+        - --title
+        - "{title}"
+        - --dry-run
+      timeout_s: 30
diff --git a/src/leapflow/gateway/adapters/feishu.py b/src/leapflow/gateway/adapters/feishu.py
index 35bcdf5..7ce2693 100644
--- a/src/leapflow/gateway/adapters/feishu.py
+++ b/src/leapflow/gateway/adapters/feishu.py
@@ -1,25 +1,35 @@
-"""Feishu/Lark gateway adapter."""
+"""Feishu/Lark adapter backed by the official lark-cli."""
 from __future__ import annotations
 
-import json
-from typing import Any, Mapping
-
-from leapflow.gateway.adapters.common import (
-    AdapterLifecycle,
-    HttpRequest,
-    HttpResponse,
-    JsonHttpClient,
-    TinyJsonHttpServer,
-    UrlLibJsonHttpClient,
-    parse_bind_port,
-    parse_json_object,
-    stable_message_id,
+from typing import Any, Mapping, Sequence
+
+from leapflow.gateway.action_packs.feishu import ACTION_SPECS
+from leapflow.gateway.adapters.common import AdapterLifecycle
+from leapflow.gateway.backends.cli_backend import CliBackend
+from leapflow.gateway.connectors.action_registry import ActionRegistry
+from leapflow.gateway.connectors.event_sources import UnavailableEventSource
+from leapflow.gateway.connectors.protocol import (
+    ActionDiscovery,
+    ActionPreview,
+    ActionResult,
+    ActionSpec,
+    BackendEventSource,
+    BackendStatus,
+    ExecutionBackend,
 )
-from leapflow.gateway.protocol import InboundMessage, OutboundContent, SendResult, SendTarget
+from leapflow.gateway.protocol import OutboundContent, SendResult, SendTarget
+
+
+class BackendNotReadyError(RuntimeError):
+    """Raised when a connector backend is installed but not ready to use."""
+
+    def __init__(self, detail: str, metadata: Mapping[str, Any]) -> None:
+        super().__init__(detail)
+        self.metadata = dict(metadata)
 
 
 class FeishuAdapter(AdapterLifecycle):
-    """Feishu adapter with token refresh, outbound text, and event normalisation."""
+    """Feishu adapter implemented through the generic CLI backend."""
 
     platform_id = "feishu"
     supports_async_delivery = True
@@ -27,150 +37,135 @@ class FeishuAdapter(AdapterLifecycle):
 
     def __init__(
         self,
-        app_id: str,
-        app_secret: str,
-        connection_mode: str = "webhook",
-        profile: str = "default",
-        api_base: str = "https://open.feishu.cn",
-        host: str = "127.0.0.1",
-        port: str | int = "9091",
-        path: str = "/feishu/events",
-        http_client: JsonHttpClient | None = None,
+        profile: str = "",
+        identity: str = "bot",
+        binary: str = "lark-cli",
+        max_message_length: int = 8000,
+        backend: ExecutionBackend | None = None,
         **_: Any,
     ) -> None:
-        super().__init__(profile=profile)
-        self._app_id = app_id
-        self._app_secret = app_secret
-        self._connection_mode = connection_mode or "webhook"
-        self._api_base = api_base.rstrip("/")
-        self._host = host or "127.0.0.1"
-        self._port = parse_bind_port(port, 9091)
-        self._path = path if str(path).startswith("/") else f"/{path}"
-        self._http = http_client or UrlLibJsonHttpClient()
-        self._tenant_access_token = ""
-        self._server: TinyJsonHttpServer | None = None
-
-    @property
-    def local_url(self) -> str:
-        if self._server is None:
-            return f"http://{self._host}:{self._port}{self._path}"
-        return f"{self._server.url_base}{self._path}"
+        super().__init__(profile=profile or "default")
+        self._profile = profile or ""
+        self._identity = identity or "bot"
+        self.max_message_length = max(1, int(max_message_length or 8000))
+        self._backend = backend or CliBackend(
+            binary=binary or "lark-cli",
+            profile=self._profile,
+            identity=self._identity,
+        )
+        discovery = self._backend if isinstance(self._backend, ActionDiscovery) else None
+        self._registry = ActionRegistry(ACTION_SPECS, discovery=discovery)
+        self._event_source = UnavailableEventSource(
+            platform_id=self.platform_id,
+            backend_kind=self._backend.kind,
+            detail=(
+                "Feishu inbound events are not enabled yet. Outbound actions can still work; "
+                "configure lark-event/WebSocket before enabling real-time message intake."
+            ),
+            metadata={
+                "available": False,
+                "configuration_hint": "Configure lark-event/WebSocket for the selected CLI profile.",
+                "current_mode": "outbound_actions_only",
+            },
+        )
 
     async def connect(self, *, is_reconnect: bool = False) -> None:
-        self._tenant_access_token = await self._fetch_tenant_access_token()
-        if self._connection_mode != "webhook":
-            raise NotImplementedError(
-                "Feishu built-in adapter currently supports connection_mode='webhook'. "
-                "WebSocket SDK mode is planned as a later adapter enhancement.",
-            )
-        if self._server is None:
-            self._server = TinyJsonHttpServer(self._host, self._port, self._handle_request)
-            await self._server.start()
+        status = await self._backend.status()
+        if not status.ok:
+            metadata = {**self.status_metadata(), **dict(status.metadata)}
+            raise BackendNotReadyError(status.detail or "Feishu CLI backend is not ready", metadata)
         await super().connect(is_reconnect=is_reconnect)
 
+    def status_metadata(self) -> dict[str, Any]:
+        """Return non-secret connector diagnostics for status/list UX."""
+        binary = getattr(self._backend, "binary", "")
+        profile = getattr(self._backend, "profile", self._profile) or "default"
+        identity = getattr(self._backend, "identity", self._identity)
+        return {
+            "backend_kind": self._backend.kind,
+            "binary": binary,
+            "profile": profile,
+            "identity": identity,
+            "actions": sorted(self._registry.all().keys()),
+            "event_source": {
+                "available": False,
+                "mode": "outbound_actions_only",
+                "hint": "Configure lark-event/WebSocket to receive Feishu events in real time.",
+            },
+        }
+
+    async def backend_status(self) -> BackendStatus:
+        """Return live backend auth diagnostics without exposing credentials."""
+        status = await self._backend.status()
+        return BackendStatus(
+            ok=status.ok,
+            backend_kind=status.backend_kind,
+            detail=status.detail,
+            metadata={**self.status_metadata(), **dict(status.metadata)},
+        )
+
     async def disconnect(self) -> None:
-        if self._server is not None:
-            await self._server.stop()
-            self._server = None
         await super().disconnect()
 
     async def send(self, target: SendTarget, content: OutboundContent) -> SendResult:
-        token = self._tenant_access_token or await self._fetch_tenant_access_token()
-        url = f"{self._api_base}/open-apis/im/v1/messages?receive_id_type=chat_id"
-        payload = {
-            "receive_id": target.chat_id,
-            "msg_type": "text",
-            "content": json.dumps({"text": content.text[:self.max_message_length]}),
-        }
-        status, data = await self._http.request_json(
-            "POST",
-            url,
-            json_body=payload,
-            headers={"Authorization": f"Bearer {token}"},
-            timeout_s=10,
-        )
-        if status >= 400 or data.get("code", 0) != 0:
-            return SendResult(ok=False, error=str(data.get("msg") or data))
-        message_id = data.get("data", {}).get("message_id", "")
-        return SendResult(ok=True, message_id=str(message_id))
-
-    async def handle_event(self, payload: Mapping[str, Any]) -> InboundMessage | None:
-        """Normalise a Feishu event callback payload and emit it."""
-        message = self.message_from_event(payload)
-        if message is None:
-            return None
-        await self._emit(message)
-        return message
-
-    async def _handle_request(self, request: HttpRequest) -> HttpResponse:
-        if request.path.split("?", 1)[0] != self._path:
-            return HttpResponse(404, {"ok": False, "error": "not found"})
-        if request.method != "POST":
-            return HttpResponse(405, {"ok": False, "error": "method not allowed"})
-        payload = parse_json_object(request.body)
-        if payload.get("type") == "url_verification" and payload.get("challenge"):
-            return HttpResponse(200, {"challenge": payload["challenge"]})
-        message = await self.handle_event(payload)
-        if message is None:
-            return HttpResponse(202, {"ok": True, "ignored": True})
-        return HttpResponse(202, {"ok": True, "message_id": message.message_id})
-
-    def message_from_event(self, payload: Mapping[str, Any]) -> InboundMessage | None:
-        event = payload.get("event") if isinstance(payload.get("event"), dict) else payload
-        if not isinstance(event, Mapping):
-            return None
-        raw_message = event.get("message") if isinstance(event.get("message"), dict) else {}
-        raw_sender = event.get("sender") if isinstance(event.get("sender"), dict) else {}
-        content = raw_message.get("content", "")
-        text = self._parse_text_content(content)
-        if not text:
-            return None
-        chat_id = str(raw_message.get("chat_id") or event.get("chat_id") or "feishu")
-        chat_type = str(raw_message.get("chat_type") or "group")
-        user_id = self._sender_id(raw_sender)
-        user_name = str(raw_sender.get("sender_type") or "")
-        message_id = str(raw_message.get("message_id") or stable_message_id("feishu"))
-        return InboundMessage(
-            source=self._source(
-                chat_id=chat_id,
-                chat_type=chat_type,
-                user_id=user_id,
-                user_name=user_name,
-            ),
-            text=text,
-            message_id=message_id,
-            metadata={"connection_mode": self._connection_mode},
+        result = await self.execute_action(
+            "im.send_message",
+            {
+                "chat_id": target.chat_id,
+                "thread_id": target.thread_id,
+                "text": content.text[:self.max_message_length],
+            },
         )
+        if not result.ok:
+            return SendResult(ok=False, error=result.error)
+        return SendResult(ok=True, message_id=result.resource_id)
 
-    async def _fetch_tenant_access_token(self) -> str:
-        status, data = await self._http.request_json(
-            "POST",
-            f"{self._api_base}/open-apis/auth/v3/tenant_access_token/internal",
-            json_body={"app_id": self._app_id, "app_secret": self._app_secret},
-            timeout_s=10,
-        )
-        token = data.get("tenant_access_token", "")
-        if status >= 400 or data.get("code", 0) != 0 or not token:
-            raise RuntimeError(str(data.get("msg") or "Feishu token request failed"))
-        return str(token)
-
-    @staticmethod
-    def _sender_id(sender: Mapping[str, Any]) -> str:
-        raw_id = sender.get("sender_id") if isinstance(sender.get("sender_id"), dict) else {}
-        if isinstance(raw_id, dict):
-            return str(raw_id.get("open_id") or raw_id.get("union_id") or raw_id.get("user_id") or "")
-        return ""
-
-    @staticmethod
-    def _parse_text_content(content: Any) -> str:
-        if isinstance(content, str):
-            try:
-                parsed = json.loads(content)
-            except json.JSONDecodeError:
-                return content
-            if isinstance(parsed, dict):
-                return str(parsed.get("text") or parsed.get("content") or "")
-            return str(parsed)
-        if isinstance(content, dict):
-            return str(content.get("text") or content.get("content") or "")
-        return str(content or "")
+    def action_specs(self) -> Mapping[str, ActionSpec]:
+        """Return Feishu actions exposed by this connector."""
+        return self._registry.all()
+
+    def action_spec(self, action: str) -> ActionSpec | None:
+        """Return one Feishu action spec."""
+        return self._registry.get(action)
+
+    async def preview_action(
+        self,
+        action: str,
+        payload: Mapping[str, Any],
+    ) -> ActionPreview:
+        """Return a side-effect-free action preview for approval."""
+        spec = self._registry.get(action)
+        if spec is None:
+            return ActionPreview(ok=False, error=f"Unknown Feishu action: {action}")
+        validation = self._registry.validate(action, payload)
+        if not validation.ok:
+            return ActionPreview(ok=False, error=validation.error)
+        preview = getattr(self._backend, "preview", None)
+        if preview is None:
+            return ActionPreview(ok=True, summary=f"Run {self.platform_id}.{action}")
+        return await preview(spec, payload)
+
+    def event_source(self) -> BackendEventSource | None:
+        """Return the configured inbound event source, if available."""
+        return self._event_source
+
+    async def discover_actions(self, *, groups: Sequence[str] = ()) -> int:
+        """Discover additional actions via CLI --help introspection.
+
+        Returns the number of newly discovered actions.
+        """
+        return await self._registry.refresh_discovery(groups=groups)
+
+    async def execute_action(
+        self,
+        action: str,
+        payload: Mapping[str, Any],
+    ) -> ActionResult:
+        """Execute a Feishu action through the configured backend."""
+        spec = self._registry.get(action)
+        if spec is None:
+            return ActionResult(ok=False, error=f"Unknown Feishu action: {action}")
+        validation = self._registry.validate(action, payload)
+        if not validation.ok:
+            return ActionResult(ok=False, error=validation.error)
+        return await self._backend.execute(spec, payload)
diff --git a/src/leapflow/gateway/backends/__init__.py b/src/leapflow/gateway/backends/__init__.py
new file mode 100644
index 0000000..3cd2385
--- /dev/null
+++ b/src/leapflow/gateway/backends/__init__.py
@@ -0,0 +1,5 @@
+"""Backend package exports."""
+from leapflow.gateway.backends.cli_backend import CliBackend
+from leapflow.gateway.backends.rest_backend import RestBackend
+
+__all__ = ["CliBackend", "RestBackend"]
diff --git a/src/leapflow/gateway/backends/cli_backend.py b/src/leapflow/gateway/backends/cli_backend.py
new file mode 100644
index 0000000..d2b0675
--- /dev/null
+++ b/src/leapflow/gateway/backends/cli_backend.py
@@ -0,0 +1,346 @@
+"""CLI execution backend for App Connector actions."""
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from contextlib import suppress
+from typing import Any, Mapping, Sequence
+
+from leapflow.gateway.connectors.cli_discovery import CliDiscovery
+from leapflow.gateway.connectors.protocol import (
+    ActionPreview,
+    ActionResult,
+    ActionSpec,
+    BackendKind,
+    BackendStatus,
+)
+from leapflow.security.redact import redact_sensitive_text
+
+
+class CliBackend:
+    """Execute registered platform actions through an official CLI binary.
+
+    Implements :class:`ActionDiscovery` via an embedded :class:`CliDiscovery`
+    instance that can discover unregistered commands through ``--help``
+    introspection.
+    """
+
+    kind = BackendKind.CLI.value
+
+    def __init__(
+        self,
+        *,
+        binary: str,
+        profile: str = "",
+        identity: str = "",
+        default_args: Sequence[str] = (),
+        timeout_s: float = 30.0,
+        discovery_cache_ttl_s: float = 3600.0,
+    ) -> None:
+        self._binary = binary
+        self._profile = profile
+        self._identity = identity
+        self._default_args = tuple(default_args)
+        self._timeout_s = timeout_s
+        self._discovery = CliDiscovery(
+            binary=binary,
+            profile=profile,
+            identity=identity,
+            default_args=default_args,
+            timeout_s=min(timeout_s, 10.0),
+            cache_ttl_s=discovery_cache_ttl_s,
+        )
+
+    @property
+    def binary(self) -> str:
+        return self._binary
+
+    @property
+    def profile(self) -> str:
+        return self._profile
+
+    @property
+    def identity(self) -> str:
+        return self._identity
+
+    async def status(self) -> BackendStatus:
+        binary_path = shutil.which(self._binary)
+        if binary_path is None:
+            return BackendStatus(
+                ok=False,
+                backend_kind=self.kind,
+                detail=f"CLI binary not found: {self._binary}",
+                metadata={
+                    **self._base_metadata(),
+                    "recoverable": True,
+                    "auth_status": "unknown",
+                    "recovery_hint": f"Install '{self._binary}' and ensure it is available on PATH.",
+                    "next_steps": [
+                        f"Install the official CLI binary '{self._binary}'.",
+                        f"Run '{self._binary} auth login --json' to authorize the selected profile.",
+                        f"Run '{self._binary} auth status --json' to verify the connection.",
+                    ],
+                },
+            )
+        command = [self._binary, *self._profile_args(), "auth", "status", "--json"]
+        result = await self._run_json(command, timeout_s=min(self._timeout_s, 10.0))
+        metadata = {**self._base_metadata(binary_path=binary_path), **dict(result.data)}
+        if result.ok:
+            metadata.setdefault("auth_status", "authorized")
+            return BackendStatus(
+                ok=True,
+                backend_kind=self.kind,
+                detail=result.error,
+                metadata=metadata,
+            )
+        metadata.update(self._recovery_metadata(result.error))
+        metadata.setdefault("detail", result.error)
+        metadata.setdefault("auth_status", "not_ready")
+        return BackendStatus(
+            ok=False,
+            backend_kind=self.kind,
+            detail=result.error,
+            metadata=metadata,
+        )
+
+    async def authenticate(self, payload: Mapping[str, Any]) -> BackendStatus:
+        domain = str(payload.get("domain") or "")
+        args = [self._binary, *self._profile_args(), "auth", "login"]
+        if domain:
+            args.extend(["--domain", domain])
+        args.extend(["--json"])
+        result = await self._run_json(args, timeout_s=self._timeout_s)
+        return BackendStatus(
+            ok=result.ok,
+            backend_kind=self.kind,
+            detail=result.error,
+            metadata=dict(result.data),
+        )
+
+    async def execute(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionResult:
+        argv_result = self._build_action_command(spec, payload)
+        if isinstance(argv_result, ActionResult):
+            return argv_result
+        return await self._run_json(
+            argv_result,
+            timeout_s=float(spec.backend_config.get("timeout_s") or self._timeout_s),
+        )
+
+    async def preview(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionPreview:
+        """Return a side-effect-free preview of the registered CLI action."""
+        argv_result = self._build_action_command(spec, payload, dry_run=True)
+        if isinstance(argv_result, ActionResult):
+            return ActionPreview(ok=False, error=argv_result.error)
+        redacted = [redact_sensitive_text(str(arg), force=True) for arg in argv_result]
+        return ActionPreview(
+            ok=True,
+            summary=self._preview_summary(spec, payload),
+            data={
+                "backend_kind": self.kind,
+                "action": spec.name,
+                "argv": redacted,
+                "dry_run": bool(spec.backend_config.get("dry_run_argv")),
+                "profile": self._profile or "default",
+                "identity": self._identity,
+                "binary": self._binary,
+            },
+        )
+
+    async def discover_actions(
+        self,
+        *,
+        groups: Sequence[str] = (),
+    ) -> list[ActionSpec]:
+        """Discover available CLI commands via ``--help`` introspection.
+
+        When *groups* is provided, only those command groups are explored.
+        Otherwise performs a full top-level discovery.
+        """
+        if groups:
+            all_commands = []
+            for group in groups:
+                all_commands.extend(await self._discovery.discover_group(group))
+        else:
+            all_commands = await self._discovery.discover_tree()
+        return [self._discovery.to_action_spec(cmd) for cmd in all_commands]
+
+    @property
+    def cli_discovery(self) -> CliDiscovery:
+        """Access the underlying discovery engine for advanced use."""
+        return self._discovery
+
+    def _build_action_command(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+        *,
+        dry_run: bool = False,
+    ) -> list[str] | ActionResult:
+        argv_template = spec.backend_config.get("dry_run_argv" if dry_run else "argv")
+        if argv_template is None and dry_run:
+            argv_template = spec.backend_config.get("argv")
+        if not isinstance(argv_template, Sequence) or isinstance(argv_template, (str, bytes)):
+            return ActionResult(ok=False, error=f"Action has no CLI argv template: {spec.name}")
+        argv = [self._render_arg(str(arg), payload) for arg in argv_template]
+        command = [self._binary, *self._profile_args(), *self._identity_args(), *self._default_args, *argv]
+        output_args = spec.backend_config.get("output_args", ())
+        if isinstance(output_args, Sequence) and not isinstance(output_args, (str, bytes)):
+            command.extend(str(a) for a in output_args)
+        else:
+            return ActionResult(ok=False, error=f"Action has invalid CLI output_args: {spec.name}")
+        return command
+
+    def _profile_args(self) -> tuple[str, ...]:
+        return ("--profile", self._profile) if self._profile else ()
+
+    def _identity_args(self) -> tuple[str, ...]:
+        return ("--as", self._identity) if self._identity else ()
+
+    def _base_metadata(self, *, binary_path: str = "") -> dict[str, Any]:
+        return {
+            "binary": self._binary,
+            "binary_path": binary_path,
+            "profile": self._profile or "default",
+            "identity": self._identity,
+            "backend_kind": self.kind,
+        }
+
+    def _recovery_metadata(self, error: str) -> dict[str, Any]:
+        status_command = " ".join([self._binary, *self._profile_args(), "auth", "status", "--json"])
+        login_command = " ".join([self._binary, *self._profile_args(), "auth", "login", "--json"])
+        lowered = error.lower()
+        if (
+            "unknown flag" in lowered
+            or "unknown command" in lowered
+            or "unknown shorthand flag" in lowered
+            or "accepts " in lowered
+        ):
+            return {
+                "recoverable": False,
+                "failure_code": "cli_contract_mismatch",
+                "recovery_hint": (
+                    f"CLI command contract mismatch — run '{self._binary} --version' to check "
+                    "the installed version and verify supported flags."
+                ),
+                "next_steps": [
+                    f"{self._binary} --version",
+                    status_command,
+                    "Update the action pack argv template if the CLI version has changed.",
+                ],
+            }
+        hint = "Authorize the selected CLI profile, then retry the platform connection."
+        if "scope" in lowered or "permission" in lowered:
+            hint = "Grant the missing permission scopes to the selected CLI identity, then retry."
+        elif "unauthor" in lowered or "login" in lowered or "token" in lowered:
+            hint = "Run CLI login for the selected profile, then retry the connection."
+        return {
+            "recoverable": True,
+            "failure_code": "auth_missing",
+            "recovery_hint": hint,
+            "next_steps": [
+                login_command,
+                status_command,
+                "Retry platform_connect after the CLI reports an authorized profile.",
+            ],
+        }
+
+    def _preview_summary(self, spec: ActionSpec, payload: Mapping[str, Any]) -> str:
+        template = spec.backend_config.get("approval_summary")
+        if isinstance(template, str) and template:
+            context: dict[str, Any] = {
+                **dict(payload),
+                "action": spec.name,
+                "binary": self._binary,
+                "profile": self._profile or "default",
+                "identity": self._identity or "default identity",
+                "backend_kind": self.kind,
+            }
+            return self._render_arg(template, context)
+        target = spec.description or f"Run {spec.name}"
+        return f"{target} via {self._binary} profile {self._profile or 'default'}"
+
+    @staticmethod
+    def _render_arg(template: str, payload: Mapping[str, Any]) -> str:
+        value = template
+        for key, raw in payload.items():
+            value = value.replace("{" + str(key) + "}", str(raw))
+        return value
+
+    async def _run_json(self, argv: Sequence[str], *, timeout_s: float) -> ActionResult:
+        proc: asyncio.subprocess.Process | None = None
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *argv,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout_s)
+        except FileNotFoundError:
+            return ActionResult(ok=False, error=f"CLI binary not found: {self._binary}")
+        except asyncio.TimeoutError:
+            if proc is not None:
+                with suppress(ProcessLookupError):
+                    proc.kill()
+                with suppress(ProcessLookupError, asyncio.TimeoutError):
+                    await asyncio.wait_for(proc.wait(), timeout=2.0)
+            return ActionResult(ok=False, error=f"CLI command timed out after {timeout_s}s")
+        except OSError as exc:
+            return ActionResult(ok=False, error=redact_sensitive_text(str(exc), force=True))
+
+        raw_stdout = stdout.decode("utf-8", errors="replace").strip()
+        raw_stderr = stderr.decode("utf-8", errors="replace").strip()
+        parsed = self._parse_json(raw_stdout or raw_stderr)
+        if proc.returncode != 0:
+            error = self._extract_error(parsed) or raw_stderr or raw_stdout or f"exit {proc.returncode}"
+            return ActionResult(ok=False, error=redact_sensitive_text(error, force=True), raw=parsed)
+        if parsed and parsed.get("ok") is False:
+            return ActionResult(
+                ok=False,
+                error=redact_sensitive_text(self._extract_error(parsed), force=True),
+                raw=parsed,
+            )
+        data = parsed.get("data") if isinstance(parsed.get("data"), dict) else parsed
+        resource_id = self._extract_resource_id(data)
+        return ActionResult(ok=True, data=data, resource_id=resource_id, raw=parsed)
+
+    @staticmethod
+    def _parse_json(raw: str) -> dict[str, Any]:
+        if not raw:
+            return {}
+        try:
+            value = json.loads(raw)
+        except json.JSONDecodeError:
+            return {"text": raw}
+        return value if isinstance(value, dict) else {"value": value}
+
+    @staticmethod
+    def _extract_error(parsed: Mapping[str, Any]) -> str:
+        error = parsed.get("error")
+        if isinstance(error, dict):
+            return str(error.get("message") or error.get("hint") or error)
+        if error:
+            return str(error)
+        if parsed.get("text"):
+            return str(parsed["text"])
+        return ""
+
+    @staticmethod
+    def _extract_resource_id(data: Mapping[str, Any]) -> str:
+        for key in ("message_id", "guid", "id", "token"):
+            value = data.get(key)
+            if value:
+                return str(value)
+        nested = data.get("message") if isinstance(data.get("message"), dict) else {}
+        if isinstance(nested, dict) and nested.get("message_id"):
+            return str(nested["message_id"])
+        return ""
diff --git a/src/leapflow/gateway/backends/rest_backend.py b/src/leapflow/gateway/backends/rest_backend.py
new file mode 100644
index 0000000..28671b9
--- /dev/null
+++ b/src/leapflow/gateway/backends/rest_backend.py
@@ -0,0 +1,118 @@
+"""REST execution backend for App Connector actions."""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from leapflow.gateway.adapters.common import JsonHttpClient, UrlLibJsonHttpClient
+from leapflow.gateway.connectors.protocol import (
+    ActionPreview,
+    ActionResult,
+    ActionSpec,
+    BackendKind,
+    BackendStatus,
+)
+from leapflow.security.redact import redact_sensitive_text
+
+
+class RestBackend:
+    """Execute registered platform actions through official REST APIs."""
+
+    kind = BackendKind.REST.value
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str = "",
+        headers: Mapping[str, str] | None = None,
+        http_client: JsonHttpClient | None = None,
+        timeout_s: float = 30.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._headers = dict(headers or {})
+        self._http = http_client or UrlLibJsonHttpClient()
+        self._timeout_s = timeout_s
+
+    async def status(self) -> BackendStatus:
+        return BackendStatus(
+            ok=bool(self._base_url),
+            backend_kind=self.kind,
+            detail="" if self._base_url else "REST base_url is required",
+        )
+
+    async def authenticate(self, payload: Mapping[str, Any]) -> BackendStatus:
+        token = str(payload.get("token") or self._token or "")
+        return BackendStatus(
+            ok=bool(token),
+            backend_kind=self.kind,
+            detail="" if token else "REST token is required",
+        )
+
+    async def execute(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionResult:
+        config = spec.backend_config
+        method = str(config.get("method") or "GET").upper()
+        path = self._render(str(config.get("path") or ""), payload)
+        body_template = config.get("json_body")
+        json_body = self._render_mapping(body_template, payload) if isinstance(body_template, Mapping) else dict(payload)
+        headers = dict(self._headers)
+        if self._token:
+            headers.setdefault("Authorization", f"Bearer {self._token}")
+        url = f"{self._base_url}/{path.lstrip('/')}"
+        try:
+            status, data = await self._http.request_json(
+                method,
+                url,
+                json_body=json_body if method != "GET" else None,
+                headers=headers,
+                timeout_s=float(config.get("timeout_s") or self._timeout_s),
+            )
+        except Exception as exc:
+            return ActionResult(ok=False, error=redact_sensitive_text(str(exc), force=True))
+        if status >= 400:
+            return ActionResult(ok=False, error=redact_sensitive_text(str(data), force=True), raw=data)
+        return ActionResult(ok=True, data=data, resource_id=self._resource_id(data), raw=data)
+
+    async def preview(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionPreview:
+        """Return a side-effect-free REST request preview."""
+        config = spec.backend_config
+        method = str(config.get("method") or "GET").upper()
+        path = self._render(str(config.get("path") or ""), payload)
+        return ActionPreview(
+            ok=True,
+            summary=f"{method} {path}",
+            data={"backend_kind": self.kind, "action": spec.name, "method": method, "path": path},
+        )
+
+    @classmethod
+    def _render_mapping(cls, template: Mapping[str, Any], payload: Mapping[str, Any]) -> dict[str, Any]:
+        result: dict[str, Any] = {}
+        for key, value in template.items():
+            if isinstance(value, str):
+                result[str(key)] = cls._render(value, payload)
+            else:
+                result[str(key)] = value
+        return result
+
+    @staticmethod
+    def _render(template: str, payload: Mapping[str, Any]) -> str:
+        value = template
+        for key, raw in payload.items():
+            value = value.replace("{" + str(key) + "}", str(raw))
+        return value
+
+    @staticmethod
+    def _resource_id(data: Mapping[str, Any]) -> str:
+        for key in ("id", "message_id", "guid", "token"):
+            value = data.get(key)
+            if value:
+                return str(value)
+        return ""
diff --git a/src/leapflow/gateway/config_store.py b/src/leapflow/gateway/config_store.py
index 83d254a..9804d73 100644
--- a/src/leapflow/gateway/config_store.py
+++ b/src/leapflow/gateway/config_store.py
@@ -176,9 +176,15 @@ def load_platform_credentials(
         config = self.load()
         pc = config.platforms.get(platform_id)
 
-        if pc is None or not pc.credentials:
+        if pc is None:
             creds = self._load_from_env(platform_id, manifest)
             return creds if creds else None
+        if not pc.credentials:
+            creds = self._load_from_env(platform_id, manifest)
+            if creds:
+                return creds
+            has_required_credentials = any(c.required for c in manifest.credentials)
+            return None if has_required_credentials else {}
 
         secret_keys = frozenset(
             c.key for c in manifest.credentials if c.secret
diff --git a/src/leapflow/gateway/connectors/__init__.py b/src/leapflow/gateway/connectors/__init__.py
new file mode 100644
index 0000000..843583f
--- /dev/null
+++ b/src/leapflow/gateway/connectors/__init__.py
@@ -0,0 +1,37 @@
+"""Connector package exports."""
+from leapflow.gateway.connectors.action_registry import ActionRegistry, summarize_action_result, validate_payload
+from leapflow.gateway.connectors.cli_discovery import CliDiscovery, DiscoveredCommand, HelpParser, HelpParseResult
+from leapflow.gateway.connectors.protocol import (
+    ActionDiscovery,
+    ActionPreview,
+    ActionResult,
+    ActionSpec,
+    AppConnector,
+    BackendEvent,
+    BackendEventSource,
+    BackendKind,
+    BackendStatus,
+    EventSourceStatus,
+    ExecutionBackend,
+)
+
+__all__ = [
+    "ActionDiscovery",
+    "ActionPreview",
+    "ActionRegistry",
+    "ActionResult",
+    "ActionSpec",
+    "AppConnector",
+    "BackendEvent",
+    "BackendEventSource",
+    "BackendKind",
+    "BackendStatus",
+    "CliDiscovery",
+    "DiscoveredCommand",
+    "EventSourceStatus",
+    "ExecutionBackend",
+    "HelpParser",
+    "HelpParseResult",
+    "summarize_action_result",
+    "validate_payload",
+]
diff --git a/src/leapflow/gateway/connectors/action_registry.py b/src/leapflow/gateway/connectors/action_registry.py
new file mode 100644
index 0000000..dad6f17
--- /dev/null
+++ b/src/leapflow/gateway/connectors/action_registry.py
@@ -0,0 +1,273 @@
+"""Action registry utilities for App Connector platform actions.
+
+Supports three sources in priority order:
+
+1. Static specs (from Python action pack or YAML) — verified, production-grade
+2. Dynamically discovered specs (via CLI ``--help``) — draft, high-risk
+3. Neither: returns ``None``
+
+Discovered specs are stored separately and never overwrite static specs.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Mapping, Sequence
+
+from leapflow.gateway.connectors.protocol import ActionResult, ActionSpec
+from leapflow.security.redact import redact_sensitive_text
+
+if TYPE_CHECKING:
+    from leapflow.gateway.connectors.protocol import ActionDiscovery
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Result of validating an action payload against a compact JSON schema subset."""
+
+    ok: bool
+    error: str = ""
+
+
+class ActionRegistry:
+    """Registry of platform actions keyed by domain.operation names.
+
+    An optional :class:`ActionDiscovery` source can be attached to
+    provide fallback command discovery when static specs lack a match.
+    Static specs always take priority over discovered ones.
+    """
+
+    def __init__(
+        self,
+        specs: Mapping[str, ActionSpec] | None = None,
+        *,
+        discovery: "ActionDiscovery | None" = None,
+    ) -> None:
+        self._specs = dict(specs or {})
+        self._discovered: dict[str, ActionSpec] = {}
+        self._discovery = discovery
+
+    @classmethod
+    def from_module(cls, module_path: str) -> "ActionRegistry":
+        """Load action specs from an action-pack module."""
+        module = import_module(module_path)
+        raw_specs = getattr(module, "ACTION_SPECS", None)
+        if raw_specs is None:
+            raw_specs = getattr(module, "FEISHU_ACTION_SPECS", None)
+        if not isinstance(raw_specs, Mapping):
+            raise ValueError(f"Action pack has no ACTION_SPECS mapping: {module_path}")
+        return cls({str(key): value for key, value in raw_specs.items()})
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str | Path) -> "ActionRegistry":
+        """Load action specs from a YAML action pack file.
+
+        YAML structure::
+
+            version: "1"
+            platform: feishu
+            actions:
+              im.send_message:
+                description: "..."
+                effect: send
+                risk_level: high
+                output_policy: summary
+                schema:
+                  required: [chat_id, text]
+                  properties:
+                    chat_id: {type: string}
+                backend:
+                  kind: cli
+                  argv: [im, +messages-send, --chat-id, "{chat_id}"]
+                  timeout_s: 30
+
+        Each ``backend.*`` field maps to ``ActionSpec.backend_config``.
+        """
+        import yaml  # pyyaml is a project dependency
+
+        with Path(yaml_path).open("r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+
+        if not isinstance(data, Mapping):
+            raise ValueError(f"YAML action pack must be a mapping: {yaml_path}")
+        actions_data = data.get("actions") or {}
+        if not isinstance(actions_data, Mapping):
+            raise ValueError(f"YAML action pack 'actions' must be a mapping: {yaml_path}")
+
+        specs: dict[str, ActionSpec] = {}
+        for name, action_data in actions_data.items():
+            if not isinstance(action_data, Mapping):
+                continue
+            backend = action_data.get("backend") or {}
+            backend_config: dict[str, Any] = {}
+            if "argv" in backend:
+                backend_config["argv"] = list(str(a) for a in (backend["argv"] or []))
+            if "dry_run_argv" in backend:
+                backend_config["dry_run_argv"] = list(str(a) for a in (backend["dry_run_argv"] or []))
+            if "approval_summary" in backend:
+                backend_config["approval_summary"] = str(backend["approval_summary"])
+            if "next_steps" in backend:
+                backend_config["next_steps"] = [str(s) for s in (backend["next_steps"] or [])]
+            if "timeout_s" in backend:
+                backend_config["timeout_s"] = float(backend["timeout_s"])
+            if "output_args" in backend:
+                backend_config["output_args"] = list(str(a) for a in (backend["output_args"] or []))
+
+            schema = action_data.get("schema") or {}
+            specs[str(name)] = ActionSpec(
+                name=str(name),
+                backend_kind=str((backend.get("kind") or "cli")),
+                description=str(action_data.get("description") or ""),
+                effect=str(action_data.get("effect") or "execute"),
+                schema=dict(schema) if isinstance(schema, Mapping) else {},
+                backend_config=backend_config,
+                risk_level=str(action_data.get("risk_level") or "medium"),
+                output_policy=str(action_data.get("output_policy") or "summary"),
+            )
+        return cls(specs)
+
+    @property
+    def discovery(self) -> "ActionDiscovery | None":
+        return self._discovery
+
+    @discovery.setter
+    def discovery(self, value: "ActionDiscovery | None") -> None:
+        self._discovery = value
+
+    def merge_discovered(self, specs: Sequence[ActionSpec]) -> int:
+        """Merge externally discovered specs without overwriting static ones.
+
+        Returns the number of newly added discovered specs.
+        """
+        added = 0
+        for spec in specs:
+            if spec.name not in self._specs and spec.name not in self._discovered:
+                self._discovered[spec.name] = spec
+                added += 1
+        return added
+
+    def all(self) -> Mapping[str, ActionSpec]:
+        """Return all action specs (static + discovered)."""
+        merged = dict(self._discovered)
+        merged.update(self._specs)
+        return merged
+
+    def static_specs(self) -> Mapping[str, ActionSpec]:
+        """Return only verified static specs."""
+        return dict(self._specs)
+
+    def discovered_specs(self) -> Mapping[str, ActionSpec]:
+        """Return only dynamically discovered specs."""
+        return dict(self._discovered)
+
+    def get(self, action: str) -> ActionSpec | None:
+        """Return an action spec — static first, then discovered."""
+        return self._specs.get(action) or self._discovered.get(action)
+
+    def is_discovered(self, action: str) -> bool:
+        """Return True if the action came from dynamic discovery."""
+        return action not in self._specs and action in self._discovered
+
+    def validate(self, action: str, payload: Mapping[str, Any]) -> ValidationResult:
+        """Validate payload using the registered action schema."""
+        spec = self.get(action)
+        if spec is None:
+            return ValidationResult(ok=False, error=f"Unknown platform action: {action}")
+        return validate_payload(spec, payload)
+
+    async def refresh_discovery(self, *, groups: Sequence[str] = ()) -> int:
+        """Run the attached discovery source and merge results.
+
+        Returns the number of newly discovered actions, or 0 if no
+        discovery source is configured.
+        """
+        if self._discovery is None:
+            return 0
+        try:
+            specs = await self._discovery.discover_actions(groups=groups)
+        except Exception as exc:
+            logger.debug("discovery.refresh_failed error=%s", exc)
+            return 0
+        return self.merge_discovered(specs)
+
+
+def validate_payload(spec: ActionSpec, payload: Mapping[str, Any]) -> ValidationResult:
+    """Validate a payload against the compact schema subset used by action packs."""
+    schema = spec.schema or {}
+    required = schema.get("required") or ()
+    missing = [str(key) for key in required if _is_missing(payload.get(str(key)))]
+    if missing:
+        return ValidationResult(ok=False, error=f"Missing required fields: {', '.join(missing)}")
+
+    properties = schema.get("properties") or {}
+    if not isinstance(properties, Mapping):
+        return ValidationResult(ok=True)
+    for key, rule in properties.items():
+        if key not in payload or payload[key] is None:
+            continue
+        if not isinstance(rule, Mapping):
+            continue
+        expected = str(rule.get("type") or "")
+        if expected and not _matches_type(payload[key], expected):
+            return ValidationResult(ok=False, error=f"Field '{key}' must be {expected}")
+    return ValidationResult(ok=True)
+
+
+def summarize_action_result(spec: ActionSpec, result: ActionResult) -> dict[str, Any]:
+    """Apply the action output policy before returning data to the LLM context."""
+    if not result.ok:
+        return {
+            "ok": False,
+            "error": redact_sensitive_text(result.error, force=True),
+            "output_policy": spec.output_policy,
+        }
+
+    summary: dict[str, Any] = {
+        "ok": True,
+        "resource_id": result.resource_id,
+        "output_policy": spec.output_policy,
+    }
+    if spec.output_policy == "raw":
+        summary["data"] = dict(result.data)
+        return summary
+
+    compact_data = _compact_data(result.data)
+    if compact_data:
+        summary["data"] = compact_data
+    if "next_steps" in spec.backend_config:
+        summary["next_steps"] = spec.backend_config["next_steps"]
+    return summary
+
+
+def _compact_data(data: Mapping[str, Any]) -> dict[str, Any]:
+    compact: dict[str, Any] = {}
+    for key in ("id", "message_id", "token", "url", "link", "permalink", "title", "name"):
+        value = data.get(key)
+        if value:
+            compact[key] = str(value)
+    nested = data.get("message") if isinstance(data.get("message"), Mapping) else None
+    if isinstance(nested, Mapping) and nested.get("message_id"):
+        compact.setdefault("message_id", str(nested["message_id"]))
+    return compact
+
+
+def _is_missing(value: Any) -> bool:
+    return value is None or value == ""
+
+
+def _matches_type(value: Any, expected: str) -> bool:
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "object":
+        return isinstance(value, Mapping)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected in {"number", "integer"}:
+        return isinstance(value, int if expected == "integer" else (int, float)) and not isinstance(value, bool)
+    return True
diff --git a/src/leapflow/gateway/connectors/cli_discovery.py b/src/leapflow/gateway/connectors/cli_discovery.py
new file mode 100644
index 0000000..b30e407
--- /dev/null
+++ b/src/leapflow/gateway/connectors/cli_discovery.py
@@ -0,0 +1,517 @@
+"""CLI help-based command discovery for App Connector backends.
+
+Discovers available commands and arguments by invoking ``<binary> --help``
+recursively, parsing the output into structured data, and generating
+draft :class:`ActionSpec` objects.  The parser uses heuristics that cover
+the most common CLI frameworks (Click, Cobra, argparse) without requiring
+LLM calls — the LLM can later match user intent against the discovered
+command index exposed in the prompt context.
+
+Design
+~~~~~~
+Three layers cooperate:
+
+1. **HelpParser** — stateless parser that turns raw ``--help`` text into
+   structured :class:`HelpParseResult` objects.
+2. **CliDiscovery** — async runner that invokes the binary, feeds output
+   into :class:`HelpParser`, and builds a command tree.
+3. **Draft ActionSpec builder** — converts discovered commands into
+   ``ActionSpec`` objects with conservative safety defaults.
+
+All discovered commands default to ``risk_level="high"`` and
+``effect="execute"`` to enforce approval before first use.
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Sequence
+
+from leapflow.gateway.connectors.protocol import ActionSpec, BackendKind
+
+# ── Data types ────────────────────────────────────────────────────────
+
+_EFFECT_HINTS: dict[str, str] = {
+    "list": "read", "get": "read", "show": "read", "search": "read",
+    "view": "read", "info": "read", "status": "read", "describe": "read",
+    "find": "read", "query": "read", "read": "read", "cat": "read",
+    "inspect": "read", "dump": "read", "export": "read", "count": "read",
+    "send": "send", "post": "send", "notify": "send", "publish": "send",
+    "forward": "send", "reply": "send", "broadcast": "send",
+    "create": "write", "add": "write", "set": "write", "update": "write",
+    "put": "write", "edit": "write", "modify": "write", "append": "write",
+    "write": "write", "insert": "write", "patch": "write", "upload": "write",
+    "delete": "execute", "remove": "execute", "drop": "execute",
+    "purge": "execute", "reset": "execute", "destroy": "execute",
+    "revoke": "execute",
+}
+
+_DANGEROUS_PATTERNS = re.compile(
+    r"\b(delete|remove|drop|purge|reset|destroy|revoke|wipe|"
+    r"force|admin|sudo|dangerous)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class HelpEntry:
+    """One command or subcommand discovered from ``--help`` output."""
+
+    name: str
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class HelpArgument:
+    """One CLI argument/flag discovered from ``--help`` output."""
+
+    name: str
+    flag: str = ""
+    description: str = ""
+    required: bool = False
+    type_hint: str = "string"
+    default: str = ""
+
+
+@dataclass(frozen=True)
+class HelpParseResult:
+    """Structured parse of a single ``--help`` invocation."""
+
+    binary: str
+    prefix: tuple[str, ...] = ()
+    description: str = ""
+    subcommands: tuple[HelpEntry, ...] = ()
+    arguments: tuple[HelpArgument, ...] = ()
+    raw_text: str = ""
+
+
+@dataclass(frozen=True)
+class DiscoveredCommand:
+    """A fully resolved CLI command path with argument metadata."""
+
+    binary: str
+    argv_prefix: tuple[str, ...]
+    description: str = ""
+    arguments: tuple[HelpArgument, ...] = ()
+    group: str = ""
+    depth: int = 0
+    discovered_at: float = field(default_factory=time.time)
+
+
+# ── Help text parser ─────────────────────────────────────────────────
+
+_SECTION_HEADER_RE = re.compile(
+    r"^(?:available\s+|positional\s+|optional\s+)?"
+    r"(commands|subcommands|options|flags|arguments|usage)"
+    r"\s*:?\s*$",
+    re.IGNORECASE,
+)
+
+_COMMAND_LINE_RE = re.compile(
+    r"^\s{2,}(\S+)\s{2,}(.+)$",
+)
+
+_FLAG_RE = re.compile(
+    r"^\s{2,}"
+    r"(?:(-\w),?\s+)?"
+    r"(--[\w][\w-]*)"
+    r"(?:\s+(\S+))?"
+    r"\s{2,}(.*)$",
+)
+
+_REQUIRED_MARKER_RE = re.compile(r"\brequired\b", re.IGNORECASE)
+
+
+class HelpParser:
+    """Parse ``--help`` output into structured data.
+
+    Handles the most common CLI help formats without requiring a specific
+    framework.  Works with Click, Cobra (Go), argparse, clap (Rust), and
+    similar two-column layouts.
+    """
+
+    def parse(
+        self,
+        raw: str,
+        *,
+        binary: str = "",
+        prefix: Sequence[str] = (),
+    ) -> HelpParseResult:
+        lines = raw.splitlines()
+        description = self._extract_description(lines)
+        subcommands = self._extract_subcommands(lines)
+        arguments = self._extract_arguments(lines)
+        return HelpParseResult(
+            binary=binary,
+            prefix=tuple(prefix),
+            description=description,
+            subcommands=tuple(subcommands),
+            arguments=tuple(arguments),
+            raw_text=raw,
+        )
+
+    def _extract_description(self, lines: list[str]) -> str:
+        """Extract the top-level description before any section header."""
+        parts: list[str] = []
+        for line in lines:
+            stripped = line.strip()
+            if not stripped:
+                if parts:
+                    break
+                continue
+            if _SECTION_HEADER_RE.match(stripped):
+                break
+            if stripped.lower().startswith("usage:"):
+                continue
+            parts.append(stripped)
+        return " ".join(parts)
+
+    def _extract_subcommands(self, lines: list[str]) -> list[HelpEntry]:
+        entries: list[HelpEntry] = []
+        in_section = False
+        for line in lines:
+            stripped = line.strip()
+            if _SECTION_HEADER_RE.match(stripped):
+                header_lower = stripped.lower()
+                in_section = (
+                    "command" in header_lower
+                    or "subcommand" in header_lower
+                    or "positional" in header_lower
+                )
+                continue
+            if in_section:
+                if not stripped:
+                    continue
+                if stripped.startswith("{") and stripped.endswith("}"):
+                    continue
+                match = _COMMAND_LINE_RE.match(line)
+                if match:
+                    name = match.group(1).strip()
+                    desc = match.group(2).strip()
+                    if not name.startswith("-"):
+                        entries.append(HelpEntry(name=name, description=desc))
+        return entries
+
+    def _extract_arguments(self, lines: list[str]) -> list[HelpArgument]:
+        args: list[HelpArgument] = []
+        in_section = False
+        for line in lines:
+            stripped = line.strip()
+            if _SECTION_HEADER_RE.match(stripped):
+                header_lower = stripped.lower()
+                in_section = any(
+                    kw in header_lower
+                    for kw in ("option", "flag", "argument")
+                )
+                continue
+            if in_section:
+                if not stripped:
+                    continue
+                match = _FLAG_RE.match(line)
+                if match:
+                    short = match.group(1) or ""
+                    long_flag = match.group(2)
+                    value_hint = match.group(3) or ""
+                    desc = match.group(4).strip()
+                    if long_flag in ("--help", "--version"):
+                        continue
+                    name = long_flag.lstrip("-").replace("-", "_")
+                    required = bool(_REQUIRED_MARKER_RE.search(desc))
+                    type_hint = self._infer_type(value_hint, desc)
+                    default = self._extract_default(desc)
+                    args.append(HelpArgument(
+                        name=name,
+                        flag=long_flag,
+                        description=desc,
+                        required=required,
+                        type_hint=type_hint,
+                        default=default,
+                    ))
+        return args
+
+    def _infer_type(self, value_hint: str, desc: str) -> str:
+        combined = f"{value_hint} {desc}".lower()
+        if any(kw in combined for kw in ("int", "number", "count", "size", "port")):
+            return "integer"
+        if any(kw in combined for kw in ("bool", "true", "false", "enable", "disable")):
+            return "boolean"
+        return "string"
+
+    def _extract_default(self, desc: str) -> str:
+        match = re.search(r"default[:\s]+['\"]?([^'\")\]]+)", desc, re.IGNORECASE)
+        return match.group(1).strip() if match else ""
+
+
+# ── Async discovery engine ───────────────────────────────────────────
+
+_DEFAULT_CACHE_TTL_S = 3600.0
+
+
+@dataclass
+class _CacheEntry:
+    result: HelpParseResult
+    expires_at: float
+
+
+class CliDiscovery:
+    """Discover CLI commands by recursively invoking ``--help``.
+
+    Results are cached in-memory with a configurable TTL. The discovery
+    tree is built lazily — call :meth:`discover_group` only when needed
+    rather than pre-scanning the entire command namespace.
+    """
+
+    def __init__(
+        self,
+        *,
+        binary: str,
+        profile: str = "",
+        identity: str = "",
+        default_args: Sequence[str] = (),
+        timeout_s: float = 10.0,
+        cache_ttl_s: float = _DEFAULT_CACHE_TTL_S,
+    ) -> None:
+        self._binary = binary
+        self._profile = profile
+        self._identity = identity
+        self._default_args = tuple(default_args)
+        self._timeout_s = timeout_s
+        self._cache_ttl_s = cache_ttl_s
+        self._cache: dict[str, _CacheEntry] = {}
+        self._parser = HelpParser()
+
+    @property
+    def binary(self) -> str:
+        return self._binary
+
+    def invalidate(self) -> None:
+        """Clear all cached help results."""
+        self._cache.clear()
+
+    async def discover(
+        self,
+        *prefix: str,
+    ) -> HelpParseResult:
+        """Run ``<binary> [prefix...] --help`` and return parsed result."""
+        cache_key = _cache_key(self._binary, prefix)
+        entry = self._cache.get(cache_key)
+        if entry is not None and entry.expires_at > time.monotonic():
+            return entry.result
+
+        argv = self._build_argv(prefix)
+        raw = await self._run_help(argv)
+        result = self._parser.parse(raw, binary=self._binary, prefix=prefix)
+        self._cache[cache_key] = _CacheEntry(
+            result=result,
+            expires_at=time.monotonic() + self._cache_ttl_s,
+        )
+        return result
+
+    async def discover_group(
+        self,
+        group: str,
+        *,
+        max_subcommands: int = 50,
+    ) -> list[DiscoveredCommand]:
+        """Discover all commands under a top-level group.
+
+        Performs a two-level traversal: ``<binary> <group> --help`` to list
+        subcommands, then ``<binary> <group> <sub> --help`` for each to
+        get argument details.
+        """
+        group_result = await self.discover(group)
+        commands: list[DiscoveredCommand] = []
+
+        if group_result.subcommands:
+            tasks = [
+                self.discover(group, sub.name)
+                for sub in group_result.subcommands[:max_subcommands]
+            ]
+            sub_results = await asyncio.gather(*tasks, return_exceptions=True)
+            for sub_entry, sub_result in zip(
+                group_result.subcommands[:max_subcommands], sub_results
+            ):
+                if isinstance(sub_result, BaseException):
+                    continue
+                commands.append(DiscoveredCommand(
+                    binary=self._binary,
+                    argv_prefix=(group, sub_entry.name),
+                    description=sub_entry.description or sub_result.description,
+                    arguments=sub_result.arguments,
+                    group=group,
+                    depth=2,
+                ))
+        elif group_result.arguments:
+            commands.append(DiscoveredCommand(
+                binary=self._binary,
+                argv_prefix=(group,),
+                description=group_result.description,
+                arguments=group_result.arguments,
+                group=group,
+                depth=1,
+            ))
+
+        return commands
+
+    async def discover_tree(
+        self,
+        *,
+        max_groups: int = 30,
+        max_subcommands: int = 50,
+    ) -> list[DiscoveredCommand]:
+        """Full two-level discovery: top-level groups → subcommands."""
+        root = await self.discover()
+        if not root.subcommands:
+            return []
+
+        tasks = [
+            self.discover_group(
+                group_entry.name,
+                max_subcommands=max_subcommands,
+            )
+            for group_entry in root.subcommands[:max_groups]
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        all_commands: list[DiscoveredCommand] = []
+        for result in results:
+            if isinstance(result, BaseException):
+                continue
+            all_commands.extend(result)
+        return all_commands
+
+    def to_action_spec(
+        self,
+        command: DiscoveredCommand,
+        *,
+        domain: str = "",
+    ) -> ActionSpec:
+        """Convert a discovered command into a draft ActionSpec."""
+        action_name = _action_name(command, domain=domain)
+        argv_template = _build_argv_template(command)
+        schema = _build_schema(command)
+        effect = _infer_effect(command)
+        risk = "critical" if _DANGEROUS_PATTERNS.search(
+            f"{' '.join(command.argv_prefix)} {command.description}"
+        ) else "high"
+
+        return ActionSpec(
+            name=action_name,
+            backend_kind=BackendKind.CLI.value,
+            description=command.description or f"Discovered CLI command: {' '.join(command.argv_prefix)}",
+            effect=effect,
+            schema=schema,
+            backend_config={
+                "argv": tuple(argv_template),
+                "timeout_s": 30,
+                "discovered": True,
+            },
+            risk_level=risk,
+            output_policy="summary",
+        )
+
+    def _build_argv(self, prefix: Sequence[str]) -> list[str]:
+        argv = [self._binary]
+        if self._profile:
+            argv.extend(["--profile", self._profile])
+        if self._identity:
+            argv.extend(["--as", self._identity])
+        argv.extend(self._default_args)
+        argv.extend(prefix)
+        argv.append("--help")
+        return argv
+
+    async def _run_help(self, argv: Sequence[str]) -> str:
+        proc = None
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *argv,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=self._timeout_s,
+            )
+        except FileNotFoundError:
+            return ""
+        except asyncio.TimeoutError:
+            if proc is not None:
+                try:
+                    proc.kill()
+                except ProcessLookupError:
+                    pass
+            return ""
+        except OSError:
+            return ""
+        return (stdout or stderr or b"").decode("utf-8", errors="replace")
+
+
+# ── Spec builders ────────────────────────────────────────────────────
+
+def _cache_key(binary: str, prefix: Sequence[str]) -> str:
+    raw = f"{binary}:{':'.join(prefix)}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def _action_name(command: DiscoveredCommand, *, domain: str = "") -> str:
+    """Build a ``domain.operation`` name from the command path."""
+    parts = list(command.argv_prefix)
+    if not parts:
+        return "unknown.unknown"
+    if domain:
+        group = domain
+    else:
+        group = parts[0].lstrip("+").replace("-", "_")
+    operation = "_".join(
+        p.lstrip("+").replace("-", "_") for p in parts[1:]
+    ) if len(parts) > 1 else parts[0].lstrip("+").replace("-", "_")
+    return f"{group}.{operation}"
+
+
+def _build_argv_template(command: DiscoveredCommand) -> list[str]:
+    """Build an argv template with ``{placeholder}`` tokens from arguments."""
+    argv: list[str] = list(command.argv_prefix)
+    for arg in command.arguments:
+        if arg.flag and arg.required:
+            argv.append(arg.flag)
+            argv.append("{" + arg.name + "}")
+    return argv
+
+
+def _build_schema(command: DiscoveredCommand) -> dict[str, Any]:
+    """Build a JSON Schema subset from discovered arguments."""
+    required: list[str] = []
+    properties: dict[str, dict[str, str]] = {}
+    for arg in command.arguments:
+        prop: dict[str, str] = {"type": arg.type_hint}
+        if arg.description:
+            prop["description"] = arg.description
+        properties[arg.name] = prop
+        if arg.required:
+            required.append(arg.name)
+    schema: dict[str, Any] = {}
+    if required:
+        schema["required"] = required
+    if properties:
+        schema["properties"] = properties
+    return schema
+
+
+def _infer_effect(command: DiscoveredCommand) -> str:
+    """Infer the action effect from the command name/description.
+
+    Uses word-boundary matching to avoid false positives (e.g. "reset"
+    must not match the "set" keyword).
+    """
+    parts = " ".join(command.argv_prefix).lower()
+    for keyword, effect in _EFFECT_HINTS.items():
+        if re.search(r"(?:^|[\W_])" + re.escape(keyword) + r"(?:$|[\W_])", parts):
+            return effect
+    desc_lower = command.description.lower()
+    for keyword, effect in _EFFECT_HINTS.items():
+        if re.search(r"(?:^|[\W_])" + re.escape(keyword) + r"(?:$|[\W_])", desc_lower):
+            return effect
+    return "execute"
diff --git a/src/leapflow/gateway/connectors/event_sources.py b/src/leapflow/gateway/connectors/event_sources.py
new file mode 100644
index 0000000..efba808
--- /dev/null
+++ b/src/leapflow/gateway/connectors/event_sources.py
@@ -0,0 +1,51 @@
+"""Reusable backend event source implementations."""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Mapping
+
+from leapflow.gateway.connectors.protocol import BackendEvent, EventSourceStatus
+
+
+class UnavailableEventSource:
+    """Event source that explicitly reports an unsupported or unconfigured inbound path."""
+
+    def __init__(
+        self,
+        *,
+        platform_id: str,
+        backend_kind: str,
+        detail: str,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.platform_id = platform_id
+        self.backend_kind = backend_kind
+        self._detail = detail
+        self._metadata = dict(metadata or {})
+        self._started = False
+
+    async def start(self, *, checkpoint: str = "") -> EventSourceStatus:
+        self._started = False
+        return EventSourceStatus(
+            ok=False,
+            backend_kind=self.backend_kind,
+            detail=self._detail,
+            checkpoint=checkpoint,
+            metadata={**self._metadata, "available": False},
+        )
+
+    async def stop(self) -> EventSourceStatus:
+        self._started = False
+        return await self.status()
+
+    async def events(self) -> AsyncIterator[BackendEvent]:
+        if False:
+            yield BackendEvent(event_id="", event_type="", platform_id=self.platform_id)
+        return
+
+    async def status(self) -> EventSourceStatus:
+        return EventSourceStatus(
+            ok=False,
+            backend_kind=self.backend_kind,
+            detail=self._detail,
+            metadata={**self._metadata, "available": False, "started": self._started},
+        )
diff --git a/src/leapflow/gateway/connectors/protocol.py b/src/leapflow/gateway/connectors/protocol.py
new file mode 100644
index 0000000..e8a7947
--- /dev/null
+++ b/src/leapflow/gateway/connectors/protocol.py
@@ -0,0 +1,199 @@
+"""App connector protocols for platform action execution.
+
+This module defines the platform-neutral contract used by REST, CLI, and
+future MCP backends. Platform-specific packages provide action specs; backend
+implementations only execute those specs and return normalized results.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, AsyncIterator, Mapping, Protocol, Sequence, runtime_checkable
+
+
+class BackendKind(str, Enum):
+    """Supported execution backend kinds."""
+
+    REST = "rest"
+    CLI = "cli"
+    MCP = "mcp"
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    """Declarative description of one platform action."""
+
+    name: str
+    backend_kind: str
+    description: str = ""
+    effect: str = "execute"
+    schema: Mapping[str, Any] = field(default_factory=dict)
+    backend_config: Mapping[str, Any] = field(default_factory=dict)
+    risk_level: str = "medium"
+    output_policy: str = "summary"
+
+
+@dataclass(frozen=True)
+class ActionResult:
+    """Backend-normalized action execution result."""
+
+    ok: bool
+    data: Mapping[str, Any] = field(default_factory=dict)
+    error: str = ""
+    resource_id: str = ""
+    raw: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ActionPreview:
+    """Side-effect-free preview used by approval UI before execution."""
+
+    ok: bool
+    summary: str = ""
+    data: Mapping[str, Any] = field(default_factory=dict)
+    error: str = ""
+
+
+@dataclass(frozen=True)
+class BackendEvent:
+    """Backend-normalized inbound event."""
+
+    event_id: str
+    event_type: str
+    platform_id: str
+    payload: Mapping[str, Any] = field(default_factory=dict)
+    checkpoint: str = ""
+
+
+@dataclass(frozen=True)
+class EventSourceStatus:
+    """Lifecycle status for a backend event source."""
+
+    ok: bool
+    backend_kind: str
+    detail: str = ""
+    checkpoint: str = ""
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class BackendStatus:
+    """Status of a backend for one configured platform/profile."""
+
+    ok: bool
+    backend_kind: str
+    detail: str = ""
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class ExecutionBackend(Protocol):
+    """Protocol implemented by all execution forms: REST, CLI, MCP, etc."""
+
+    kind: str
+
+    async def status(self) -> BackendStatus:
+        """Return backend availability and authentication status."""
+        ...
+
+    async def authenticate(self, payload: Mapping[str, Any]) -> BackendStatus:
+        """Run backend-specific authentication or return guidance."""
+        ...
+
+    async def execute(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionResult:
+        """Execute a registered action spec with validated payload."""
+        ...
+
+    async def preview(
+        self,
+        spec: ActionSpec,
+        payload: Mapping[str, Any],
+    ) -> ActionPreview:
+        """Return a side-effect-free preview for approval UI."""
+        ...
+
+
+@runtime_checkable
+class BackendEventSource(Protocol):
+    """Protocol implemented by CLI, REST, webhook, or MCP event sources."""
+
+    platform_id: str
+    backend_kind: str
+
+    async def start(self, *, checkpoint: str = "") -> EventSourceStatus:
+        """Start receiving events from the backend."""
+        ...
+
+    async def stop(self) -> EventSourceStatus:
+        """Stop receiving events from the backend."""
+        ...
+
+    async def events(self) -> AsyncIterator[BackendEvent]:
+        """Yield normalized inbound events."""
+        ...
+
+    async def status(self) -> EventSourceStatus:
+        """Return current event source health."""
+        ...
+
+
+@runtime_checkable
+class ActionDiscovery(Protocol):
+    """Protocol for backends that support dynamic command discovery.
+
+    Implementations run ``--help`` or equivalent introspection to discover
+    available commands, converting them into draft :class:`ActionSpec`
+    objects with conservative safety defaults (``risk_level="high"``).
+    """
+
+    async def discover_actions(
+        self,
+        *,
+        groups: Sequence[str] = (),
+    ) -> list[ActionSpec]:
+        """Discover available actions, optionally scoped to command groups.
+
+        When *groups* is empty, performs a full top-level discovery.
+        When *groups* is provided, only discovers commands under those
+        specific command groups (e.g. ``["im", "calendar"]``).
+        """
+        ...
+
+
+@runtime_checkable
+class AppConnector(Protocol):
+    """Platform-level connector that exposes actions through one backend."""
+
+    platform_id: str
+
+    def action_specs(self) -> Mapping[str, ActionSpec]:
+        """Return available actions keyed by domain.operation."""
+        ...
+
+    def action_spec(self, action: str) -> ActionSpec | None:
+        """Return one registered action spec, if available."""
+        ...
+
+    async def preview_action(
+        self,
+        action: str,
+        payload: Mapping[str, Any],
+    ) -> ActionPreview:
+        """Return a side-effect-free action preview."""
+        ...
+
+    def event_source(self) -> BackendEventSource | None:
+        """Return the inbound event source, if this connector supports one."""
+        ...
+
+    async def execute_action(
+        self,
+        action: str,
+        payload: Mapping[str, Any],
+    ) -> ActionResult:
+        """Validate and execute a platform action."""
+        ...
diff --git a/src/leapflow/gateway/manifest.py b/src/leapflow/gateway/manifest.py
index 1aaa92f..8057732 100644
--- a/src/leapflow/gateway/manifest.py
+++ b/src/leapflow/gateway/manifest.py
@@ -87,6 +87,9 @@ class PlatformManifest:
     validation_method: str = ""
     validation_timeout_s: float = 10.0
     adapter: Optional[AdapterSpec] = None
+    backend: Dict[str, Any] = field(default_factory=dict)
+    actions: Dict[str, Any] = field(default_factory=dict)
+    extra_fields: Dict[str, Any] = field(default_factory=dict)
     source_path: str = ""
 
 
@@ -180,6 +183,11 @@ def _parse(self, path: Path) -> PlatformManifest:
             )
 
         validation_raw = raw.get("validation", {})
+        known_keys = {
+            "platform_id", "display_name", "description", "category",
+            "credentials", "options", "setup_guide", "validation",
+            "adapter", "backend", "actions",
+        }
         return PlatformManifest(
             platform_id=raw["platform_id"],
             display_name=raw.get("display_name", raw["platform_id"]),
@@ -191,5 +199,8 @@ def _parse(self, path: Path) -> PlatformManifest:
             validation_method=validation_raw.get("method", ""),
             validation_timeout_s=float(validation_raw.get("timeout_s", 10)),
             adapter=adapter,
+            backend=dict(raw.get("backend") or {}),
+            actions=dict(raw.get("actions") or {}),
+            extra_fields={key: value for key, value in raw.items() if key not in known_keys},
             source_path=str(path),
         )
diff --git a/src/leapflow/gateway/manifests/feishu.yaml b/src/leapflow/gateway/manifests/feishu.yaml
index 51e66f5..2a4d14b 100644
--- a/src/leapflow/gateway/manifests/feishu.yaml
+++ b/src/leapflow/gateway/manifests/feishu.yaml
@@ -1,67 +1,76 @@
 platform_id: feishu
 display_name: "飞书 (Feishu/Lark)"
-description: "飞书企业即时通讯平台"
+description: "飞书企业协作平台（官方 lark-cli 后端）"
 category: im
 
-credentials:
-  - key: app_id
-    label: App ID
-    required: true
-    secret: false
-    help_zh: "登录 open.feishu.cn → 创建企业自建应用 → 凭证与基础信息 → 复制 App ID"
-    help_en: "Login open.feishu.cn → Create App → Credentials → Copy App ID"
-  - key: app_secret
-    label: App Secret
-    required: true
-    secret: true
-    help_zh: "同页面 → 复制 App Secret"
-    help_en: "Same page → Copy App Secret"
+credentials: []
 
 options:
-  - key: connection_mode
-    label: 连接模式
-    type: choice
-    choices: [webhook]
-    default: webhook
-    help_zh: "当前内置适配器使用本地 HTTP Webhook 接收事件；WebSocket SDK 模式将作为后续增强"
-    help_en: "The built-in adapter currently receives events through a local HTTP webhook; SDK WebSocket mode is a later enhancement"
-  - key: host
-    label: 绑定地址
-    type: string
-    default: "127.0.0.1"
-    help_zh: "Webhook 服务绑定地址（默认仅本机访问）"
-    help_en: "Webhook server bind address (default: localhost only)"
-  - key: port
-    label: 端口
+  - key: profile
+    label: CLI Profile
     type: string
-    default: "9091"
-    help_zh: "Webhook 服务端口"
-    help_en: "Webhook server port"
-  - key: path
-    label: 路径
+    default: ""
+    help_zh: "lark-cli profile 名称；为空时使用 lark-cli 当前默认 profile"
+    help_en: "lark-cli profile name; empty means the current default profile"
+  - key: identity
+    label: 执行身份
+    type: choice
+    choices: [bot, user]
+    default: bot
+    help_zh: "通过 lark-cli --as 指定 bot 或 user 身份"
+    help_en: "Identity passed through lark-cli --as"
+  - key: binary
+    label: CLI 命令
     type: string
-    default: "/feishu/events"
-    help_zh: "飞书事件回调路径"
-    help_en: "Feishu event callback path"
+    default: "lark-cli"
+    advanced: true
+    help_zh: "飞书官方 CLI 可执行文件名或路径"
+    help_en: "Official lark-cli executable name or path"
+  - key: max_message_length
+    label: 最大消息长度
+    type: integer
+    default: 8000
+    advanced: true
+    help_zh: "发送 IM 文本前在 LeapFlow 侧保留的最大字符数"
+    help_en: "Maximum text characters retained by LeapFlow before sending IM messages"
 
 setup_guide:
   summary_zh: |
-    接入飞书需要在飞书开放平台创建一个企业自建应用并开启机器人能力。
-    完成后请提供 App ID 和 App Secret。
+    LeapFlow 使用飞书官方 lark-cli 接入飞书能力。请先安装并完成一次 CLI 应用配置与授权。
   summary_en: |
-    To connect Feishu, create an enterprise app on open.feishu.cn
-    with bot capability enabled. Then provide your App ID and App Secret.
+    LeapFlow uses the official lark-cli backend for Feishu/Lark. Install and authorize lark-cli first.
   steps_zh:
-    - "打开 https://open.feishu.cn/app → 点击「创建企业自建应用」"
-    - "在「应用能力」中启用「机器人」"
-    - "在「凭证与基础信息」页面复制 App ID 和 App Secret"
-    - "在「权限管理」中添加：im:message、im:message.group_at_msg"
-  console_url: "https://open.feishu.cn/app"
+    - "安装：npx @larksuite/cli@latest install"
+    - "初始化应用配置：lark-cli config init --new"
+    - "登录授权：lark-cli auth login --recommend"
+    - "验证状态：lark-cli auth status"
+  steps_en:
+    - "Install: npx @larksuite/cli@latest install"
+    - "Initialize app config: lark-cli config init --new"
+    - "Authorize: lark-cli auth login --recommend"
+    - "Verify: lark-cli auth status"
+  console_url: "https://github.com/larksuite/cli"
 
 validation:
-  method: feishu_token_check
+  method: ""
   timeout_s: 10
 
+backend:
+  kind: cli
+  binary: lark-cli
+  format: json
+
+actions:
+  pack: leapflow.gateway.action_packs.feishu
+  initial_domains: [im, docs, calendar, drive, sheets, mail, task]
+
+events:
+  kind: cli
+  status: unavailable
+  command: lark-event
+  checkpoint: profile
+  note: "Enable after lark-event/WebSocket is configured; no legacy webhook fallback."
+
 adapter:
   module: leapflow.gateway.adapters.feishu
   class: FeishuAdapter
diff --git a/src/leapflow/gateway/router.py b/src/leapflow/gateway/router.py
index 8798910..a24a210 100644
--- a/src/leapflow/gateway/router.py
+++ b/src/leapflow/gateway/router.py
@@ -21,15 +21,12 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
 from typing import Any, Callable, Coroutine, Dict, List, Optional, Sequence
 
-from leapflow.gateway.protocol import (
-    InboundMessage,
-    MessageSource,
-    OutboundContent,
-    SendTarget,
-)
+from leapflow.gateway.protocol import InboundMessage, MessageSource
+from leapflow.tools.name_resolver import ToolRegistry
 
 logger = logging.getLogger(__name__)
 
@@ -41,6 +38,7 @@
     "skills_list", "skill_view",
     "text_search",
     "gateway_connect", "gateway_send",
+    "platform_connect", "platform_action",
 })
 
 
@@ -97,6 +95,7 @@ def __init__(
         self._tool_handlers = {
             k: v for k, v in all_handlers.items() if k in allowed_tools
         }
+        self._tool_registry = ToolRegistry.from_definitions(self._tool_defs, self._tool_handlers)
 
     async def handle_message(
         self,
@@ -161,21 +160,32 @@ async def _llm_with_tools(
                 return (resp.content or "").strip()
 
             for tc in tool_calls:
-                handler = self._tool_handlers.get(tc.name)
+                tool_args = getattr(tc, "arguments", {})
+                if isinstance(tool_args, str):
+                    try:
+                        tool_args = json.loads(tool_args)
+                    except json.JSONDecodeError:
+                        tool_args = {}
+                if not isinstance(tool_args, dict):
+                    tool_args = {}
+
+                resolution = self._tool_registry.resolve(tc.name, tool_args)
+                handler = (
+                    self._tool_handlers.get(resolution.normalized_name)
+                    if resolution.auto_executable and resolution.normalized_name
+                    else None
+                )
                 if handler is None:
+                    unknown = self._tool_registry.unknown_result(resolution)
                     history.append({
                         "role": "tool",
                         "tool_call_id": getattr(tc, "id", ""),
-                        "content": f"Unknown tool: {tc.name}",
+                        "content": json.dumps(unknown, default=str, ensure_ascii=False),
                     })
                     continue
                 try:
-                    tool_args = getattr(tc, "arguments", {})
-                    if isinstance(tool_args, str):
-                        import json
-                        tool_args = json.loads(tool_args)
                     result = await asyncio.wait_for(handler(tool_args), timeout=30)
-                    result_text = str(result)[:2000]
+                    result_text = json.dumps(result, default=str, ensure_ascii=False)[:2000]
                 except asyncio.TimeoutError:
                     result_text = f"Tool '{tc.name}' timed out"
                 except Exception as exc:
diff --git a/src/leapflow/gateway/server.py b/src/leapflow/gateway/server.py
index ecb7ec1..7986f35 100644
--- a/src/leapflow/gateway/server.py
+++ b/src/leapflow/gateway/server.py
@@ -23,6 +23,8 @@
 from typing import Any, Callable, Dict, List, Optional
 
 from leapflow.gateway.config_store import GatewayConfigStore
+from leapflow.gateway.connectors.action_registry import summarize_action_result
+from leapflow.gateway.connectors.protocol import ActionPreview, ActionSpec, BackendEventSource, EventSourceStatus
 from leapflow.gateway.credential_vault import CredentialVault
 from leapflow.gateway.events import (
     GatewayMessageReceived,
@@ -63,6 +65,7 @@ def __init__(
         self._manifest_loader = ManifestLoader(extra_dirs=extra_manifest_dirs)
         self._manifests: Dict[str, PlatformManifest] = {}
         self._adapters: Dict[str, PlatformAdapter] = {}
+        self._event_sources: Dict[str, BackendEventSource] = {}
         self._connected_since: Dict[str, float] = {}
         self._known_sessions: set[SessionKey] = set()
         self._message_handler: Optional[Callable[..., Any]] = None
@@ -139,21 +142,36 @@ async def connect_platform(
             except Exception as exc:
                 from leapflow.security.redact import redact_sensitive_text
 
+                metadata = getattr(exc, "metadata", {})
                 safe_err = redact_sensitive_text(str(exc), force=True)
                 logger.error("Failed to connect %s: %s", platform_id, safe_err)
-                return {"ok": False, "error": f"Connection failed: {safe_err}"}
+                response: Dict[str, Any] = {"ok": False, "error": f"Connection failed: {safe_err}"}
+                if isinstance(metadata, dict):
+                    if metadata.get("recovery_hint"):
+                        response["recovery_hint"] = metadata["recovery_hint"]
+                    if metadata.get("next_steps"):
+                        response["next_steps"] = metadata["next_steps"]
+                    response["diagnostics"] = self._safe_metadata(metadata)
+                return response
 
         display = manifest.display_name
-        return {
+        response = {
             "ok": True,
             "status": "connected",
             "platform": display,
             "info": validation_info,
         }
+        adapter = self._adapters.get(platform_id)
+        if adapter is not None:
+            diagnostics = self._adapter_metadata(adapter)
+            if diagnostics:
+                response["diagnostics"] = diagnostics
+        return response
 
     async def disconnect_platform(self, platform_id: str) -> Dict[str, Any]:
         """Disconnect a platform adapter and clean up its sessions."""
         adapter = self._adapters.pop(platform_id, None)
+        self._event_sources.pop(platform_id, None)
         self._connected_since.pop(platform_id, None)
 
         affected = {k for k in self._known_sessions if k.platform == platform_id}
@@ -179,16 +197,20 @@ def platform_status(self) -> List[PlatformStatus]:
         config = self._config_store.load()
         for pid in self._manifests:
             if pid in self._adapters:
+                adapter = self._adapters[pid]
                 result.append(PlatformStatus(
                     platform_id=pid,
                     connected=True,
                     connected_since=self._connected_since.get(pid, 0),
+                    metadata=self._adapter_metadata(adapter),
                 ))
             elif pid in config.platforms and config.platforms[pid].enabled:
+                metadata = self._configured_platform_metadata(pid, config.platforms[pid].options)
                 result.append(PlatformStatus(
                     platform_id=pid,
                     connected=False,
                     error="configured but not connected",
+                    metadata=metadata,
                 ))
             else:
                 result.append(PlatformStatus(
@@ -216,7 +238,7 @@ async def start(self) -> int:
                 creds = self._config_store.load_platform_credentials(
                     pid, manifest,
                 )
-                if not creds:
+                if creds is None:
                     continue
                 result = await self.connect_platform(
                     pid, creds, pc.options,
@@ -279,6 +301,167 @@ async def send_message(
             safe_err = redact_sensitive_text(str(exc), force=True)
             return {"ok": False, "error": f"Send failed: {safe_err}"}
 
+    def get_platform_action_spec(self, platform_id: str, action: str) -> ActionSpec | None:
+        """Return a registered action spec for a connected platform."""
+        adapter = self._adapters.get(platform_id)
+        if adapter is None:
+            return None
+        action_spec = getattr(adapter, "action_spec", None)
+        if action_spec is not None:
+            return action_spec(action)
+        action_specs = getattr(adapter, "action_specs", None)
+        if action_specs is None:
+            return None
+        specs = action_specs()
+        return specs.get(action) if isinstance(specs, dict) else None
+
+    async def preview_platform_action(
+        self,
+        platform_id: str,
+        action: str,
+        payload: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Return a side-effect-free action preview for approval UX."""
+        adapter = self._adapters.get(platform_id)
+        if adapter is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' is not connected"}
+        preview = getattr(adapter, "preview_action", None)
+        if preview is None:
+            spec = self.get_platform_action_spec(platform_id, action)
+            if spec is None:
+                return {"ok": False, "error": f"Unknown platform action: {action}"}
+            return {"ok": True, "summary": f"Run {platform_id}.{action}"}
+        result: ActionPreview = await preview(action, payload)
+        return {
+            "ok": result.ok,
+            "summary": result.summary,
+            "data": dict(result.data),
+            **({"error": result.error} if result.error else {}),
+        }
+
+    async def execute_platform_action(
+        self,
+        platform_id: str,
+        action: str,
+        payload: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        """Execute a registered platform action via the connected adapter."""
+        adapter = self._adapters.get(platform_id)
+        if adapter is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' is not connected"}
+        execute = getattr(adapter, "execute_action", None)
+        if execute is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' does not support platform actions"}
+        try:
+            spec = self.get_platform_action_spec(platform_id, action)
+            result = await execute(action, payload)
+            if spec is not None:
+                summary = summarize_action_result(spec, result)
+                summary.update({"platform": platform_id, "action": action})
+                return summary
+            return {
+                "ok": bool(getattr(result, "ok", False)),
+                "data": dict(getattr(result, "data", {}) or {}),
+                "resource_id": str(getattr(result, "resource_id", "") or ""),
+                **({"error": str(getattr(result, "error", ""))} if getattr(result, "error", "") else {}),
+            }
+        except Exception as exc:
+            from leapflow.security.redact import redact_sensitive_text
+            safe_err = redact_sensitive_text(str(exc), force=True)
+            return {"ok": False, "error": f"Platform action failed: {safe_err}"}
+
+    async def start_platform_events(
+        self,
+        platform_id: str,
+        *,
+        checkpoint: str = "",
+    ) -> Dict[str, Any]:
+        """Start the backend event source for a connected platform."""
+        adapter = self._adapters.get(platform_id)
+        if adapter is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' is not connected"}
+        event_source_factory = getattr(adapter, "event_source", None)
+        if event_source_factory is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' has no backend event source"}
+        source = event_source_factory()
+        if source is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' has no backend event source"}
+        status: EventSourceStatus = await source.start(checkpoint=checkpoint)
+        if status.ok:
+            self._event_sources[platform_id] = source
+        return self._event_status_dict(status)
+
+    async def stop_platform_events(self, platform_id: str) -> Dict[str, Any]:
+        """Stop the backend event source for a connected platform."""
+        source = self._event_sources.pop(platform_id, None)
+        if source is None:
+            return {"ok": True, "status": "stopped"}
+        status = await source.stop()
+        return self._event_status_dict(status)
+
+    async def platform_event_status(self, platform_id: str) -> Dict[str, Any]:
+        """Return backend event source status for a connected platform."""
+        source = self._event_sources.get(platform_id)
+        if source is None:
+            adapter = self._adapters.get(platform_id)
+            event_source_factory = getattr(adapter, "event_source", None) if adapter else None
+            source = event_source_factory() if event_source_factory else None
+        if source is None:
+            return {"ok": False, "error": f"Platform '{platform_id}' has no backend event source"}
+        status = await source.status()
+        return self._event_status_dict(status)
+
+    @staticmethod
+    def _event_status_dict(status: EventSourceStatus) -> Dict[str, Any]:
+        return {
+            "ok": status.ok,
+            "backend_kind": status.backend_kind,
+            "detail": status.detail,
+            "checkpoint": status.checkpoint,
+            "metadata": dict(status.metadata),
+        }
+
+    def _adapter_metadata(self, adapter: PlatformAdapter) -> Dict[str, Any]:
+        metadata_factory = getattr(adapter, "status_metadata", None)
+        if metadata_factory is None:
+            return {}
+        try:
+            metadata = metadata_factory()
+        except Exception:
+            logger.debug("platform.status_metadata_failed", exc_info=True)
+            return {}
+        return self._safe_metadata(metadata if isinstance(metadata, dict) else {})
+
+    def _configured_platform_metadata(self, platform_id: str, options: Dict[str, Any]) -> Dict[str, Any]:
+        manifest = self._manifests.get(platform_id)
+        metadata: Dict[str, Any] = {"configured": True}
+        if manifest is not None:
+            metadata["backend_kind"] = str(manifest.backend.get("kind") or "")
+            if manifest.actions:
+                metadata["actions"] = dict(manifest.actions)
+        if options:
+            for key in ("profile", "identity", "binary"):
+                if options.get(key):
+                    metadata[key] = options[key]
+        metadata["recovery_hint"] = "Reconnect the platform or inspect backend status for details."
+        return self._safe_metadata(metadata)
+
+    @staticmethod
+    def _safe_metadata(metadata: Dict[str, Any]) -> Dict[str, Any]:
+        from leapflow.security.redact import redact_sensitive_text
+
+        safe: Dict[str, Any] = {}
+        for key, value in metadata.items():
+            if isinstance(value, str):
+                safe[key] = redact_sensitive_text(value, force=True)
+            elif isinstance(value, list):
+                safe[key] = [redact_sensitive_text(str(item), force=True) for item in value]
+            elif isinstance(value, dict):
+                safe[key] = GatewayServer._safe_metadata(value)
+            else:
+                safe[key] = value
+        return safe
+
     async def send_reply(
         self,
         source: MessageSource,
diff --git a/src/leapflow/gateway/validators.py b/src/leapflow/gateway/validators.py
index ae70b9e..e58d59a 100644
--- a/src/leapflow/gateway/validators.py
+++ b/src/leapflow/gateway/validators.py
@@ -11,7 +11,7 @@
 
 import asyncio
 import logging
-from typing import Awaitable, Callable, Dict, Optional, Tuple
+from typing import Any, Awaitable, Callable, Dict, Optional, Tuple
 
 logger = logging.getLogger(__name__)
 
@@ -65,7 +65,7 @@ async def validate_credentials(
 # Built-in validators (for bundled manifests)
 # ═══════════════════════════════════════════════════════════════
 
-def _make_client_timeout() -> "aiohttp.ClientTimeout":
+def _make_client_timeout() -> Any:
     """Create a strict per-request timeout for credential validation.
 
     Imported lazily to avoid top-level ``aiohttp`` dependency.
diff --git a/src/leapflow/prompts/templates.py b/src/leapflow/prompts/templates.py
index c8cd9d2..75a336b 100644
--- a/src/leapflow/prompts/templates.py
+++ b/src/leapflow/prompts/templates.py
@@ -75,19 +75,30 @@ def build_react_system(language: str = "en", skill_catalog: str = "") -> str:
 ## Capabilities
 You have access to these tools:
 {tool_catalog}
-{skill_section}
+{app_connector_section}{skill_section}
 ## Tool Usage
 Call tools using JSON code blocks:
 ```json
 {{"name": "tool_name", "arguments": {{"key": "value"}}}}
 ```
+Only call a tool whose exact name appears in the tool list above. Never invent, rename, alias, or guess a
+tool name, platform ID, or platform action from argument shape or wording. If no exact tool matches, say
+so or ask for clarification instead of guessing. `platform_connect.action` (list/guide/preflight/connect/
+disconnect/remove/status/events_start/events_stop/events_status) is the App Connector management
+namespace; `platform_action.action` only accepts exact registered business actions such as
+`im.send_message` shown in the App Connector Capability Index — never mix the two namespaces. If a tool
+call returns an unknown/unavailable result, use the returned suggestions or available names for a single
+retry instead of trying further variations of the same guess. For `platform_action` calls with
+`effect=send` or `effect=write` (e.g. `im.send_message`, `docs.create_markdown`), include
+**exactly one** call per assistant turn — do not repeat the same action+payload as a confirmation
+pass or pre-flight attempt; the system enforces this and will discard duplicates.
 
 ## Guidelines
 1. **Direct answers first**: If you already know the answer, respond directly without tools.
 2. **Avoid redundant tool calls**: Do not call the same tool with the same arguments more than once in the same user turn. When an existing tool result already answers the user's request, stop calling tools and answer directly.
 3. **Use tools proactively**: When the user asks about files, time, system state, or needs actions performed, use the appropriate tool.
 4. **Chain tools when needed**: You can call multiple tools in sequence (e.g., list files → read file → summarize).
-5. **Handle failures gracefully**: If a tool fails, explain what went wrong and suggest alternatives.
+5. **Handle failures gracefully**: If a tool fails, explain what went wrong and suggest alternatives. If it failed because of an unknown tool/platform/action name, retry once with an exact name from the returned suggestions, then explain rather than keep guessing.
 6. **Summarize results naturally**: After tool execution, synthesize the results into a helpful answer rather than dumping raw output.
 7. **Stay conversational**: Maintain a natural, helpful tone. Acknowledge context from earlier in the conversation.
 
diff --git a/src/leapflow/security/actions.py b/src/leapflow/security/actions.py
index 3326d8d..8b4eafb 100644
--- a/src/leapflow/security/actions.py
+++ b/src/leapflow/security/actions.py
@@ -17,6 +17,7 @@ class ActionKind(str, Enum):
     FILE_WRITE = "file.write"
     FILE_DELETE = "file.delete"
     GATEWAY_SEND = "gateway.send"
+    PLATFORM_ACTION = "platform.action"
     SCHEDULER_ARM = "scheduler.arm"
     SKILL_EXECUTE = "skill.execute"
     SKILL_PROMOTE = "skill.promote"
@@ -128,6 +129,34 @@ def gateway_send(
             metadata=merged,
         )
 
+    @classmethod
+    def platform_action(
+        cls,
+        platform: str,
+        action: str,
+        payload: dict[str, Any],
+        *,
+        backend_kind: str = "",
+        metadata: dict[str, Any] | None = None,
+    ) -> "ActionDescriptor":
+        """Describe a platform action before backend execution."""
+        merged = dict(metadata or {})
+        merged.update({
+            "platform": platform,
+            "action": action,
+            "backend_kind": backend_kind,
+        })
+        effect = str(merged.get("effect") or _effect_for_platform_action(action))
+        detail = json.dumps(payload, ensure_ascii=False, sort_keys=True)[:1000]
+        return cls(
+            kind=ActionKind.PLATFORM_ACTION.value,
+            summary=f"Run {platform}.{action}",
+            detail=detail,
+            effect=effect,
+            resource=f"{platform}:{action}",
+            metadata=merged,
+        )
+
     def signature(self) -> str:
         """Return a stable signature suitable for session/profile grants."""
         payload = {
@@ -169,12 +198,23 @@ def _summarize_shell(command: str) -> str:
     return "Run shell command"
 
 
+def _effect_for_platform_action(action: str) -> str:
+    lowered = action.lower()
+    if any(token in lowered for token in ("send", "reply", "message")):
+        return ActionEffect.SEND.value
+    if any(token in lowered for token in ("delete", "remove")):
+        return ActionEffect.DELETE.value
+    if any(token in lowered for token in ("create", "update", "write", "append", "approve")):
+        return ActionEffect.WRITE.value
+    return ActionEffect.READ.value
+
+
 def _normalize_resource(resource: str) -> str:
     return resource.replace("\\", "/").strip().lower()
 
 
 def _normalize_detail(kind: str, detail: str) -> str:
     text = re.sub(r"\s+", " ", detail.strip())
-    if kind == ActionKind.GATEWAY_SEND.value:
-        return "<message>"
+    if kind in {ActionKind.GATEWAY_SEND.value, ActionKind.PLATFORM_ACTION.value}:
+        return "<platform-payload>"
     return text[:4000]
diff --git a/src/leapflow/security/risk.py b/src/leapflow/security/risk.py
index 32fab13..24bdeea 100644
--- a/src/leapflow/security/risk.py
+++ b/src/leapflow/security/risk.py
@@ -108,6 +108,26 @@ def assess(self, action: ActionDescriptor) -> RiskAssessment:
                 explanation="This sends content to an external platform conversation.",
                 allow_permanent=False,
             )
+        if action.kind == ActionKind.PLATFORM_ACTION.value:
+            explicit_level = self._platform_risk_level(action)
+            if explicit_level is not None:
+                return explicit_level
+            if action.effect == "read":
+                return RiskAssessment(
+                    level=RiskLevel.MEDIUM,
+                    score=0.5,
+                    reasons=("platform_data_access",),
+                    explanation="This reads data from an external platform.",
+                    metadata={"backend_kind": action.metadata.get("backend_kind", "")},
+                )
+            return RiskAssessment(
+                level=RiskLevel.HIGH,
+                score=0.74,
+                reasons=("external_platform_action",),
+                explanation="This performs an action through an external platform backend.",
+                allow_permanent=False,
+                metadata={"backend_kind": action.metadata.get("backend_kind", "")},
+            )
         if action.kind in {
             ActionKind.SCHEDULER_ARM.value,
             ActionKind.SKILL_PROMOTE.value,
@@ -123,6 +143,36 @@ def assess(self, action: ActionDescriptor) -> RiskAssessment:
             )
         return RiskAssessment(level=RiskLevel.MEDIUM, score=0.5, reasons=("external_action",))
 
+    @staticmethod
+    def _platform_risk_level(action: ActionDescriptor) -> RiskAssessment | None:
+        raw = str(action.metadata.get("risk_level") or "").lower()
+        if not raw:
+            return None
+        try:
+            level = RiskLevel(raw)
+        except ValueError:
+            return None
+        score_by_level = {
+            RiskLevel.SAFE: 0.05,
+            RiskLevel.LOW: 0.2,
+            RiskLevel.MEDIUM: 0.5,
+            RiskLevel.HIGH: 0.78,
+            RiskLevel.CRITICAL: 0.95,
+        }
+        return RiskAssessment(
+            level=level,
+            score=score_by_level[level],
+            reasons=("registered_platform_action",),
+            explanation="This risk level comes from the registered platform action spec.",
+            hardline=level == RiskLevel.CRITICAL,
+            allow_permanent=level not in {RiskLevel.HIGH, RiskLevel.CRITICAL},
+            metadata={
+                "backend_kind": action.metadata.get("backend_kind", ""),
+                "platform": action.metadata.get("platform", ""),
+                "action": action.metadata.get("action", ""),
+            },
+        )
+
     def _assess_shell(self, action: ActionDescriptor) -> RiskAssessment:
         command = action.detail
         for pattern, reason in self._SHELL_HARDLINE:
diff --git a/src/leapflow/security/threat_patterns.py b/src/leapflow/security/threat_patterns.py
index cdc1ad0..90f9109 100644
--- a/src/leapflow/security/threat_patterns.py
+++ b/src/leapflow/security/threat_patterns.py
@@ -17,7 +17,7 @@
 import unicodedata
 from dataclasses import dataclass
 from enum import Enum
-from typing import List, Optional, Sequence
+from typing import List, Optional
 
 
 class ThreatScope(Enum):
diff --git a/src/leapflow/tools/file_operations.py b/src/leapflow/tools/file_operations.py
index 8c4db27..750548b 100644
--- a/src/leapflow/tools/file_operations.py
+++ b/src/leapflow/tools/file_operations.py
@@ -142,6 +142,11 @@ def _is_device_path(path: Path) -> bool:
     return resolved.startswith("/dev/") or resolved.startswith("/proc/")
 
 
+def _is_unsupported_leapflow_config_probe(path: Path) -> bool:
+    parts = path.parts
+    return len(parts) >= 2 and parts[-2:] == (".leapflow", "config.json")
+
+
 async def file_list(params: Dict[str, Any]) -> Dict[str, Any]:
     """List directory contents with optional glob pattern."""
     path = params.get("path", ".")
@@ -190,6 +195,18 @@ async def file_read(params: Dict[str, Any]) -> Dict[str, Any]:
         return {"ok": False, "error": f"Device path reads are blocked: {path}"}
 
     if not target.exists():
+        if _is_unsupported_leapflow_config_probe(target):
+            return {
+                "ok": False,
+                "error": (
+                    "LeapFlow does not use <workspace>/.leapflow/config.json. "
+                    "Use ~/.leapflow/.env for global runtime config, or an existing ./.env "
+                    "for project overrides."
+                ),
+                "error_type": "unsupported_config_probe",
+                "retryable": False,
+                "config_locations": ["~/.leapflow/.env", "./.env"],
+            }
         return {"ok": False, "error": f"File not found: {path}"}
     if not target.is_file():
         return {"ok": False, "error": f"Not a file: {path}"}
diff --git a/src/leapflow/tools/gateway_tool.py b/src/leapflow/tools/gateway_tool.py
index 1d79b49..9f0ba35 100644
--- a/src/leapflow/tools/gateway_tool.py
+++ b/src/leapflow/tools/gateway_tool.py
@@ -11,17 +11,37 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Mapping
 
 logger = logging.getLogger(__name__)
 
 _gateway_server_ref: Any = None
 _approval_gate: Any = None
+_pending_app_onboarding: Dict[str, Any] | None = None
+
+# Single source of truth for the platform_connect management namespace. Both
+# the platform_connect tool schema enum and the platform_action namespace
+# guard below are generated from this tuple so the two never drift apart.
+PLATFORM_CONNECT_ACTIONS: tuple[str, ...] = (
+    "list",
+    "guide",
+    "preflight",
+    "connect",
+    "disconnect",
+    "remove",
+    "status",
+    "events_start",
+    "events_stop",
+    "events_status",
+)
+_PLATFORM_CONNECT_ACTIONS = frozenset(PLATFORM_CONNECT_ACTIONS)
 
 
 def set_gateway_server(server: Any) -> None:
     """Install ``GatewayServer`` reference for tool dispatch (late-bound)."""
-    global _gateway_server_ref
+    global _gateway_server_ref, _pending_app_onboarding
+    if server is not _gateway_server_ref:
+        _pending_app_onboarding = None
     _gateway_server_ref = server
 
 
@@ -31,6 +51,107 @@ def set_gateway_approval_gate(gate: Any) -> None:
     _approval_gate = gate
 
 
+def build_app_connector_prompt_section() -> str:
+    """Build a compact App Connector capability index for the current prompt.
+
+    This function does not classify user text. It only exposes the currently
+    supported platform manifests so the LLM can use its normal language
+    understanding in the same turn and choose the right connector tool.
+    """
+    if _gateway_server_ref is None:
+        return ""
+    manifests = getattr(_gateway_server_ref, "manifests", {}) or {}
+    if not manifests:
+        return ""
+
+    lines = [
+        "\n## App Connector Capability Index",
+        "LeapFlow can onboard and manage external apps through `platform_connect` and execute exact registered business actions through `platform_action`.",
+        "For requests about connecting, setting up, configuring, enabling, or managing a supported app, use `platform_connect` first instead of generating SDK/Webhook sample code.",
+        f"`platform_connect.action` is the management namespace: {', '.join(PLATFORM_CONNECT_ACTIONS)}.",
+        "`platform_action.action` is only for exact registered platform business actions listed below, such as `im.send_message`; never use management actions like `list` or `guide` there.",
+        "Do not invent platform IDs or platform action names. If the needed action is not listed, ask for discovery/clarification instead of guessing.",
+        "Use `platform_connect` with `action='guide'` and the matching `platform` to start onboarding; use `action='list'` when the app is unclear.",
+        "When a pending onboarding state is present, continue from that state with `platform_connect` instead of asking the user to restate the app.",
+        "Supported apps:",
+    ]
+    for platform_id, manifest in sorted(manifests.items()):
+        backend = dict(getattr(manifest, "backend", {}) or {})
+        backend_kind = str(backend.get("kind") or "adapter")
+        action_summaries = _platform_action_summaries(platform_id)
+        action_names = ", ".join(f"`{item['name']}`" for item in action_summaries[:12])
+        action_text = f"; platform_action actions={action_names}" if action_names else "; platform_action actions=none registered"
+        lines.append(
+            f"- `{platform_id}`: {getattr(manifest, 'display_name', platform_id)} "
+            f"(category={getattr(manifest, 'category', '')}; backend={backend_kind}{action_text})"
+        )
+    if _pending_app_onboarding:
+        state = dict(_pending_app_onboarding)
+        next_actions = state.get("next_actions") or []
+        next_text = "; next=" + " | ".join(str(item) for item in next_actions[:3]) if next_actions else ""
+        lines.extend([
+            "",
+            "Pending App Onboarding State:",
+            (
+                f"- platform=`{state.get('platform_id', '')}`; stage={state.get('stage', 'unknown')}; "
+                f"backend={state.get('backend_kind', 'unknown')}; recoverable={state.get('recoverable', True)}{next_text}"
+            ),
+            "Use this state to continue app onboarding; do not ask the user to repeat known platform details.",
+        ])
+    return "\n".join(lines) + "\n"
+
+
+def _manifest_action_specs(platform: str) -> Mapping[str, Any]:
+    """Return action-pack specs declared by a platform manifest."""
+    manifest = _gateway_server_ref.manifests.get(platform) if _gateway_server_ref is not None else None
+    if manifest is None:
+        return {}
+    actions = dict(getattr(manifest, "actions", {}) or {})
+    pack = str(actions.get("pack") or "")
+    if not pack:
+        return {}
+    try:
+        from leapflow.gateway.connectors.action_registry import ActionRegistry
+
+        return ActionRegistry.from_module(pack).all()
+    except (ImportError, AttributeError, ValueError):
+        logger.debug("platform.action_pack_lookup_failed platform=%s", platform, exc_info=True)
+        return {}
+
+
+def _compact_action_summary(spec: Any) -> Dict[str, Any]:
+    """Return a compact, LLM-readable platform action contract entry."""
+    schema = getattr(spec, "schema", {}) or {}
+    required = schema.get("required") or () if isinstance(schema, Mapping) else ()
+    properties = schema.get("properties") or {} if isinstance(schema, Mapping) else {}
+    return {
+        "name": str(getattr(spec, "name", "") or ""),
+        "description": str(getattr(spec, "description", "") or ""),
+        "effect": str(getattr(spec, "effect", "") or ""),
+        "risk_level": str(getattr(spec, "risk_level", "") or ""),
+        "required": [str(item) for item in required],
+        "fields": [str(key) for key in properties.keys()] if isinstance(properties, Mapping) else [],
+    }
+
+
+def _platform_action_summaries(platform: str) -> List[Dict[str, Any]]:
+    """Return registered platform action summaries sorted by action name."""
+    specs = _manifest_action_specs(platform)
+    return [
+        _compact_action_summary(spec)
+        for _name, spec in sorted(specs.items())
+    ]
+
+
+def platform_action_capability_summary(platform: str) -> List[Dict[str, Any]]:
+    """Public accessor for registered platform action summaries.
+
+    Used by slash commands and other callers that need to display the exact
+    business action contract without reaching into module-private state.
+    """
+    return _platform_action_summaries(platform)
+
+
 # ═══════════════════════════════════════════════════════════════
 # Tool handler
 # ═══════════════════════════════════════════════════════════════
@@ -66,6 +187,40 @@ async def gateway_connect_handler(params: Dict[str, Any]) -> Dict[str, Any]:
     return await handler(platform, params)
 
 
+async def platform_connect_handler(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Handle platform connection management across backend kinds."""
+    if _gateway_server_ref is None:
+        return {"ok": False, "error": "Gateway not initialised"}
+    action = params.get("action", "list")
+    platform = params.get("platform", "")
+    if action == "connect":
+        if not platform:
+            return {"ok": False, "error": "platform is required"}
+        return await _action_connect(platform, params)
+    if action == "preflight":
+        if not platform:
+            return {"ok": False, "error": "platform is required"}
+        return await _action_preflight(platform, params)
+    if action == "events_start":
+        if not platform:
+            return {"ok": False, "error": "platform is required"}
+        return await _gateway_server_ref.start_platform_events(
+            platform,
+            checkpoint=str(params.get("checkpoint") or ""),
+        )
+    if action == "events_stop":
+        if not platform:
+            return {"ok": False, "error": "platform is required"}
+        return await _gateway_server_ref.stop_platform_events(platform)
+    if action == "events_status":
+        if not platform:
+            return {"ok": False, "error": "platform is required"}
+        return await _gateway_server_ref.platform_event_status(platform)
+    if action in {"list", "guide", "disconnect", "remove", "status"}:
+        return await gateway_connect_handler(params)
+    return {"ok": False, "error": f"Unknown action: {action}"}
+
+
 # ── Action implementations ───────────────────────────────────
 
 async def _action_list(
@@ -90,6 +245,8 @@ async def _action_list(
         if s.connected and s.connected_since > 0:
             uptime_s = int(time.time() - s.connected_since)
             entry["uptime"] = _format_uptime(uptime_s)
+        if getattr(s, "metadata", None):
+            entry["diagnostics"] = dict(s.metadata)
         platforms.append(entry)
     return {"ok": True, "platforms": platforms}
 
@@ -156,6 +313,16 @@ async def _action_guide(
     if options:
         result["optional_settings"] = options
 
+    preflight_checks = _manifest_preflight_checks(manifest)
+    if preflight_checks:
+        result["preflight_checks"] = preflight_checks
+        preflight = await _run_manifest_preflight(platform, manifest, _params)
+        result["preflight_result"] = preflight
+        result["onboarding_state"] = _remember_app_onboarding(platform, manifest, preflight)
+        result["recovery_hint"] = preflight.get("recovery_hint") or "Complete the preflight checks first; LeapFlow will then reuse the authorized backend profile."
+        if preflight.get("next_steps"):
+            result["next_steps"] = preflight["next_steps"]
+
     result["setup_form"] = {
         "fields": [
             {
@@ -167,15 +334,24 @@ async def _action_guide(
             for c in manifest.credentials
         ],
         "console_url": manifest.setup_guide.console_url,
+        "backend": dict(manifest.backend),
+        "actions": dict(manifest.actions),
     }
 
     required = [c for c in manifest.credentials if c.required]
-    labels = " / ".join(c.label for c in required)
-    result["prompt_hint"] = (
-        f"Present the setup steps above, then ask the user to provide "
-        f"{labels} in a single reply.  Do NOT repeat credential values "
-        f"in your response."
-    )
+    if required:
+        labels = " / ".join(c.label for c in required)
+        result["prompt_hint"] = (
+            f"Present the setup steps above, then ask the user to provide "
+            f"{labels} in a single reply.  Do NOT repeat credential values "
+            f"in your response."
+        )
+    else:
+        result["prompt_hint"] = (
+            "Present the setup steps and current preflight result. If all safe checks are ready, "
+            "call platform_connect with action='connect'. If a preflight step requires installation, "
+            "authorization, or credentials, ask only for that missing user action and avoid repeating known details."
+        )
 
     return result
 
@@ -188,17 +364,184 @@ async def _action_connect(
     SECURITY: credentials flow into ``connect_platform()`` which encrypts
     and persists them.  Return value contains **only** status.
     """
+    manifest = _gateway_server_ref.manifests.get(platform)
     credentials = params.get("credentials", {})
     options = params.get("options", {})
 
     if not platform:
         return {"ok": False, "error": "Platform ID is required"}
-    if not credentials:
+    if manifest is None:
+        return {"ok": False, "error": f"Unknown platform: {platform}"}
+    has_required_credentials = any(c.required for c in manifest.credentials)
+    if has_required_credentials and not credentials:
         return await _action_guide(platform, params)
 
-    return await _gateway_server_ref.connect_platform(
+    result = await _gateway_server_ref.connect_platform(
         platform, credentials, options,
     )
+    return _decorate_app_connection_result(platform, manifest, result)
+
+
+async def _action_preflight(
+    platform: str, params: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Run safe manifest-driven preflight checks for a platform."""
+    manifest = _gateway_server_ref.manifests.get(platform)
+    if not platform:
+        return {"ok": False, "error": "Platform ID is required"}
+    if manifest is None:
+        return {"ok": False, "error": f"Unknown platform: {platform}"}
+    preflight = await _run_manifest_preflight(platform, manifest, params)
+    state = _remember_app_onboarding(platform, manifest, preflight)
+    return {
+        "ok": bool(preflight.get("ready")),
+        "platform": platform,
+        "stage": state.get("stage"),
+        "preflight_result": preflight,
+        "onboarding_state": state,
+        "recovery_hint": preflight.get("recovery_hint", ""),
+        "next_steps": list(preflight.get("next_steps") or ()),
+    }
+
+
+def _decorate_app_connection_result(platform: str, manifest: Any, result: Dict[str, Any]) -> Dict[str, Any]:
+    response = dict(result)
+    if response.get("ok"):
+        response["onboarding_state"] = _remember_app_onboarding(
+            platform,
+            manifest,
+            {
+                "ready": True,
+                "stage": "connected",
+                "backend_kind": _manifest_backend_kind(manifest),
+                "recoverable": False,
+                "next_steps": [],
+            },
+        )
+        return response
+
+    diagnostics = dict(response.get("diagnostics") or response.get("metadata") or {})
+    stage = _stage_from_backend_metadata(diagnostics, default="connect_failed")
+    preflight = {
+        "ready": False,
+        "stage": stage,
+        "backend_kind": _manifest_backend_kind(manifest),
+        "recoverable": bool(diagnostics.get("recoverable", True)),
+        "recovery_hint": response.get("recovery_hint") or diagnostics.get("recovery_hint") or response.get("error", ""),
+        "next_steps": response.get("next_steps") or diagnostics.get("next_steps") or [],
+        "metadata": diagnostics,
+    }
+    response["onboarding_state"] = _remember_app_onboarding(platform, manifest, preflight)
+    response.setdefault("recovery_hint", preflight["recovery_hint"])
+    if preflight["next_steps"]:
+        response.setdefault("next_steps", preflight["next_steps"])
+    return response
+
+
+def _manifest_backend_kind(manifest: Any) -> str:
+    backend = dict(getattr(manifest, "backend", {}) or {})
+    return str(backend.get("kind") or "adapter")
+
+
+def _manifest_option_default(manifest: Any, key: str, fallback: Any = "") -> Any:
+    for option in getattr(manifest, "options", ()) or ():
+        if str(getattr(option, "key", "")) == key:
+            value = getattr(option, "default", fallback)
+            return fallback if value is None else value
+    return fallback
+
+
+def _stage_from_backend_metadata(metadata: Dict[str, Any], *, default: str) -> str:
+    detail = str(metadata.get("detail") or metadata.get("error") or metadata.get("last_error") or "").lower()
+    auth_status = str(metadata.get("auth_status") or "").lower()
+    failure_code = str(metadata.get("failure_code") or metadata.get("error_code") or "").lower()
+    if failure_code == "cli_contract_mismatch":
+        return "cli_contract_mismatch"
+    if metadata.get("binary_path") or auth_status == "authorized":
+        if auth_status == "authorized":
+            return "auth_ready"
+        if auth_status in {"not_ready", "unknown"}:
+            return "auth_missing"
+        return default
+    if "binary not found" in detail or "not found" in detail or auth_status == "unknown":
+        return "cli_missing"
+    if "unauthor" in detail or "login" in detail or "token" in detail:
+        return "auth_missing"
+    return default
+
+
+async def _run_manifest_preflight(platform: str, manifest: Any, params: Dict[str, Any]) -> Dict[str, Any]:
+    backend_kind = _manifest_backend_kind(manifest)
+    if backend_kind != "cli":
+        return {
+            "ready": True,
+            "stage": "ready",
+            "backend_kind": backend_kind,
+            "recoverable": False,
+            "checks": [],
+            "next_steps": [f"platform_connect action=connect platform={platform}"],
+        }
+
+    from leapflow.gateway.backends.cli_backend import CliBackend
+
+    backend = dict(getattr(manifest, "backend", {}) or {})
+    options = dict(params.get("options") or {})
+    binary = str(options.get("binary") or backend.get("binary") or _manifest_option_default(manifest, "binary", "lark-cli"))
+    profile = str(options.get("profile") or _manifest_option_default(manifest, "profile", ""))
+    identity = str(options.get("identity") or _manifest_option_default(manifest, "identity", ""))
+    status = await CliBackend(binary=binary, profile=profile, identity=identity, timeout_s=6.0).status()
+    metadata = dict(status.metadata)
+    stage = "auth_ready" if status.ok else _stage_from_backend_metadata(metadata, default="auth_missing")
+    checks = _preflight_checks_with_status(_manifest_preflight_checks(manifest), stage)
+    next_steps = list(metadata.get("next_steps") or [])
+    if status.ok:
+        next_steps = [f"platform_connect action=connect platform={platform}"]
+    return {
+        "ready": bool(status.ok),
+        "stage": stage,
+        "backend_kind": backend_kind,
+        "recoverable": bool(metadata.get("recoverable", not status.ok)),
+        "checks": checks,
+        "detail": status.detail,
+        "metadata": metadata,
+        "recovery_hint": metadata.get("recovery_hint", "") if not status.ok else "CLI backend is authorized; continue with platform_connect action='connect'.",
+        "next_steps": next_steps,
+    }
+
+
+def _preflight_checks_with_status(checks: list[Dict[str, Any]], stage: str) -> list[Dict[str, Any]]:
+    decorated: list[Dict[str, Any]] = []
+    for check in checks:
+        item = dict(check)
+        key = str(item.get("key") or "")
+        if stage == "auth_ready":
+            item["status"] = "passed"
+        elif stage == "cli_missing":
+            item["status"] = "failed" if key == "cli_installed" else "blocked"
+        elif stage == "auth_missing":
+            item["status"] = "passed" if key == "cli_installed" else ("failed" if key == "cli_status" else "blocked")
+        elif stage == "cli_contract_mismatch":
+            item["status"] = "passed" if key == "cli_installed" else ("failed" if key == "cli_status" else "blocked")
+        else:
+            item["status"] = "pending"
+        decorated.append(item)
+    return decorated
+
+
+def _remember_app_onboarding(platform: str, manifest: Any, preflight: Dict[str, Any]) -> Dict[str, Any]:
+    global _pending_app_onboarding
+    state = {
+        "platform_id": platform,
+        "platform": getattr(manifest, "display_name", platform),
+        "stage": preflight.get("stage") or "unknown",
+        "backend_kind": preflight.get("backend_kind") or _manifest_backend_kind(manifest),
+        "ready": bool(preflight.get("ready")),
+        "recoverable": bool(preflight.get("recoverable", True)),
+        "last_error": preflight.get("detail") or preflight.get("recovery_hint") or "",
+        "next_actions": list(preflight.get("next_steps") or ()),
+    }
+    _pending_app_onboarding = state if state["stage"] != "connected" else None
+    return state
 
 
 async def _action_disconnect(
@@ -243,6 +586,10 @@ def _status_entry(s: Any) -> Dict[str, Any]:
             entry["error"] = s.error
         if s.connected and s.connected_since > 0:
             entry["uptime"] = _format_uptime(int(time.time() - s.connected_since))
+        if getattr(s, "metadata", None):
+            entry["diagnostics"] = dict(s.metadata)
+            if s.metadata.get("recovery_hint"):
+                entry["recovery_hint"] = s.metadata["recovery_hint"]
         return entry
 
     if platform:
@@ -256,6 +603,113 @@ def _status_entry(s: Any) -> Dict[str, Any]:
     return {"ok": True, "platforms": [_status_entry(s) for s in statuses]}
 
 
+def _manifest_preflight_checks(manifest: Any) -> list[Dict[str, Any]]:
+    backend = dict(getattr(manifest, "backend", {}) or {})
+    if backend.get("kind") != "cli":
+        return []
+    binary = str(backend.get("binary") or "lark-cli")
+    return [
+        {
+            "key": "cli_installed",
+            "label": "Install CLI",
+            "kind": "check",
+            "auto_run": True,
+            "requires_approval": False,
+            "command": f"{binary} --version",
+            "help": f"Ensure '{binary}' is installed and available on PATH.",
+            "failure_code": "cli_missing",
+        },
+        {
+            "key": "cli_authorized",
+            "label": "Authorize profile",
+            "kind": "interactive_auth",
+            "auto_run": False,
+            "requires_approval": True,
+            "command": f"{binary} auth login --json",
+            "help": "Authorize the selected CLI identity once in the official CLI.",
+            "failure_code": "auth_missing",
+        },
+        {
+            "key": "cli_status",
+            "label": "Verify status",
+            "kind": "check",
+            "auto_run": True,
+            "requires_approval": False,
+            "command": f"{binary} auth status --json",
+            "help": "Confirm the selected CLI profile is ready before connecting.",
+            "failure_code": "auth_missing",
+        },
+    ]
+
+
+def _manifest_action_spec(platform: str, action: str) -> Any:
+    return _manifest_action_specs(platform).get(action)
+
+
+def _platform_action_unavailable_response(platform: str, action: str) -> Dict[str, Any]:
+    manifest = _gateway_server_ref.manifests.get(platform) if _gateway_server_ref is not None else None
+    available_platforms = sorted((_gateway_server_ref.manifests or {}).keys()) if _gateway_server_ref is not None else []
+    if manifest is None:
+        return {
+            "ok": False,
+            "failure_code": "unknown_platform",
+            "error": f"Unknown platform: {platform}",
+            "available_platforms": available_platforms,
+            "recovery_hint": "Use platform_connect action=list to inspect supported platform IDs before calling platform_action.",
+            "retryable": True,
+        }
+    action_summaries = _platform_action_summaries(platform)
+    action_names = [item["name"] for item in action_summaries if item.get("name")]
+    if action in _PLATFORM_CONNECT_ACTIONS:
+        return {
+            "ok": False,
+            "failure_code": "wrong_action_namespace",
+            "error": f"'{action}' is a platform_connect management action, not a platform_action business action.",
+            "platform": platform,
+            "requested_action": action,
+            "tool_namespace": "platform_action",
+            "correct_tool": "platform_connect",
+            "available_management_actions": sorted(_PLATFORM_CONNECT_ACTIONS),
+            "available_actions": action_summaries,
+            "available_action_names": action_names,
+            "recovery_hint": f"Call platform_connect with platform='{platform}' and action='{action}', or choose one exact business action from available_action_names for platform_action.",
+            "retryable": True,
+        }
+    if _manifest_action_spec(platform, action) is None:
+        return {
+            "ok": False,
+            "failure_code": "unknown_platform_action",
+            "error": f"Unknown platform action: {platform}.{action}",
+            "platform": platform,
+            "requested_action": action,
+            "available_actions": action_summaries,
+            "available_action_names": action_names,
+            "recovery_hint": "Use exactly one registered platform_action action name from available_action_names; do not infer or invent action names from domains.",
+            "retryable": True,
+        }
+    recovery_hint = "Connect the platform backend before running registered platform actions."
+    next_steps = [
+        f"platform_connect action=guide platform={platform}",
+        f"platform_connect action=preflight platform={platform}",
+        f"platform_connect action=connect platform={platform}",
+    ]
+    response: Dict[str, Any] = {
+        "ok": False,
+        "failure_code": "platform_not_connected",
+        "error": f"Platform '{platform}' is not connected; registered action '{action}' cannot run yet.",
+        "platform": platform,
+        "requested_action": action,
+        "available_actions": action_summaries,
+        "available_action_names": action_names,
+        "recovery_hint": recovery_hint,
+        "next_steps": next_steps,
+        "retryable": True,
+    }
+    if _pending_app_onboarding and _pending_app_onboarding.get("platform_id") == platform:
+        response["onboarding_state"] = dict(_pending_app_onboarding)
+    return response
+
+
 # ═══════════════════════════════════════════════════════════════
 # gateway_send handler — proactive outbound messaging
 # ═══════════════════════════════════════════════════════════════
@@ -282,6 +736,28 @@ async def gateway_send_handler(params: Dict[str, Any]) -> Dict[str, Any]:
     if not text:
         return {"ok": False, "error": "text is required"}
 
+    spec = _gateway_server_ref.get_platform_action_spec(platform, "im.send_message")
+    if spec is None:
+        unavailable = _platform_action_unavailable_response(platform, "im.send_message")
+        if unavailable.get("failure_code") != "unknown_platform_action":
+            return unavailable
+    else:
+        delegated = await platform_action_handler({
+            "platform": platform,
+            "action": "im.send_message",
+            "payload": {
+                "chat_id": chat_id,
+                "text": text,
+                "thread_id": params.get("thread_id", ""),
+            },
+            "source_tool": "gateway_send",
+        })
+        if delegated.get("ok"):
+            if delegated.get("resource_id") and "message_id" not in delegated:
+                delegated["message_id"] = delegated["resource_id"]
+            delegated.setdefault("source_tool", "gateway_send")
+        return delegated
+
     if _approval_gate is not None:
         try:
             from leapflow.security.actions import ActionDescriptor
@@ -323,11 +799,127 @@ async def gateway_send_handler(params: Dict[str, Any]) -> Dict[str, Any]:
     )
 
 
+async def platform_action_handler(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Execute a registered platform action through the gateway boundary."""
+    if _gateway_server_ref is None:
+        return {"ok": False, "error": "Gateway not initialised"}
+    platform = str(params.get("platform") or "")
+    action_name = str(params.get("action") or "")
+    payload = params.get("payload") or {}
+    if not isinstance(payload, dict):
+        return {"ok": False, "error": "payload must be an object"}
+    if not platform:
+        return {"ok": False, "error": "platform is required"}
+    if not action_name:
+        return {"ok": False, "error": "action is required"}
+
+    spec = _gateway_server_ref.get_platform_action_spec(platform, action_name)
+    if spec is None:
+        return _platform_action_unavailable_response(platform, action_name)
+    preview = await _gateway_server_ref.preview_platform_action(platform, action_name, payload)
+    if not preview.get("ok"):
+        return {"ok": False, "error": str(preview.get("error") or "Platform action preview failed")}
+
+    if _approval_gate is not None:
+        try:
+            from leapflow.security.actions import ActionDescriptor
+            from leapflow.security.approval import ApprovalDecision, ApprovalRequest
+
+            approval_action = ActionDescriptor.platform_action(
+                platform,
+                action_name,
+                payload,
+                backend_kind=spec.backend_kind,
+                metadata={
+                    "effect": spec.effect,
+                    "risk_level": spec.risk_level,
+                    "output_policy": spec.output_policy,
+                    "preview": preview.get("summary", ""),
+                },
+            )
+            if hasattr(_approval_gate, "evaluate"):
+                result = await _approval_gate.evaluate(approval_action)
+                if not getattr(result, "approved", False):
+                    error = str(getattr(result, "denial_message", "") or "Platform action denied by approval gate")
+                    return {"ok": False, "error": error}
+            else:
+                decision = await _approval_gate.request_approval(ApprovalRequest(
+                    category=approval_action.kind,
+                    detail=str(preview.get("summary") or approval_action.summary),
+                    risk_hint=0.6,
+                    metadata={
+                        "platform": platform,
+                        "action": action_name,
+                        "backend_kind": spec.backend_kind,
+                        "risk_level": spec.risk_level,
+                    },
+                    action=approval_action,
+                ))
+                if decision not in {
+                    ApprovalDecision.ALLOW,
+                    ApprovalDecision.ALLOW_ONCE,
+                    ApprovalDecision.ALLOW_SESSION,
+                    ApprovalDecision.ALLOW_ALWAYS,
+                }:
+                    return {"ok": False, "error": "Platform action denied by approval gate"}
+        except Exception:
+            logger.debug("platform_action approval check failed", exc_info=True)
+            return {"ok": False, "error": "Platform action approval check failed"}
+
+    return await _gateway_server_ref.execute_platform_action(platform, action_name, payload)
+
+
 # ═══════════════════════════════════════════════════════════════
 # Tool registration (OpenAI function calling schema)
 # ═══════════════════════════════════════════════════════════════
 
 GATEWAY_TOOL_DEFINITIONS: List[Dict[str, Any]] = [
+    {
+        "type": "function",
+        "function": {
+            "name": "platform_action",
+            "description": (
+                "Execute an exact registered business action on an external platform through "
+                "LeapFlow's App Connector layer. Actions must be copied from the App Connector "
+                "Capability Index/available_action_names and are addressed as domain.operation, "
+                "e.g. im.send_message or docs.create_markdown. Do not invent action names, do not "
+                "use management actions such as list/guide/connect/status here, and never pass raw CLI commands or URLs."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "platform": {"type": "string", "description": "Platform ID, e.g. feishu"},
+                    "action": {"type": "string", "description": "Exact registered business action from available_action_names, e.g. im.send_message; never list/guide/connect/status"},
+                    "payload": {"type": "object", "description": "Action payload matching the registered schema"},
+                    "backend_kind": {"type": "string", "description": "Optional backend hint: cli/rest/mcp"},
+                },
+                "required": ["platform", "action", "payload"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "platform_connect",
+            "description": (
+                "List, guide, connect, disconnect, remove, or check status for external "
+                "platforms using the App Connector management namespace. Supports REST and CLI "
+                "backends. Use this for management actions such as list/guide/preflight/connect/status; "
+                "use platform_action only for exact registered business actions."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "action": {"type": "string", "enum": list(PLATFORM_CONNECT_ACTIONS)},
+                    "platform": {"type": "string", "description": "Platform ID"},
+                    "credentials": {"type": "object", "description": "Optional credentials for REST-style backends"},
+                    "options": {"type": "object", "description": "Backend options such as profile, identity, or binary"},
+                    "checkpoint": {"type": "string", "description": "Optional event source resume checkpoint"},
+                },
+                "required": ["action"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -417,6 +1009,29 @@ async def gateway_send_handler(params: Dict[str, Any]) -> Dict[str, Any]:
 ]
 
 GATEWAY_BRIDGE_TOOLS: List[Dict[str, Any]] = [
+    {
+        "name": "gp_platform_connect",
+        "description": "Connect or manage external platform integrations via App Connector.",
+        "parameters": {
+            "action": "string (required) — list/guide/connect/disconnect/remove/status/events_start/events_stop/events_status",
+            "platform": "string (optional) — platform ID",
+            "credentials": "object (optional) — backend credentials",
+            "options": "object (optional) — backend options",
+            "checkpoint": "string (optional) — event source resume checkpoint",
+        },
+        "handler": platform_connect_handler,
+    },
+    {
+        "name": "gp_platform_action",
+        "description": "Execute a registered platform action via App Connector.",
+        "parameters": {
+            "platform": "string (required) — platform ID",
+            "action": "string (required) — domain.operation",
+            "payload": "object (required) — action payload",
+        },
+        "handler": platform_action_handler,
+        "mutates_state": True,
+    },
     {
         "name": "gp_gateway_connect",
         "description": "Connect or manage external platform integrations.",
@@ -442,6 +1057,10 @@ async def gateway_send_handler(params: Dict[str, Any]) -> Dict[str, Any]:
 ]
 
 GATEWAY_TOOL_HANDLERS: Dict[str, Any] = {
+    "platform_connect": platform_connect_handler,
+    "gp_platform_connect": platform_connect_handler,
+    "platform_action": platform_action_handler,
+    "gp_platform_action": platform_action_handler,
     "gateway_connect": gateway_connect_handler,
     "gp_gateway_connect": gateway_connect_handler,
     "gateway_send": gateway_send_handler,
diff --git a/src/leapflow/tools/name_resolver.py b/src/leapflow/tools/name_resolver.py
index e18f68e..b9999b4 100644
--- a/src/leapflow/tools/name_resolver.py
+++ b/src/leapflow/tools/name_resolver.py
@@ -1,8 +1,13 @@
 """Tool registry and name-resolution primitives.
 
-This module centralizes tool identity, safe aliases, risk metadata, and
-structured unknown-tool feedback. It is intentionally execution-free: callers
-resolve a tool name here, then execute through their existing dispatch path.
+This module centralizes the Tool Capability Contract: the set of canonical
+tool names the runtime can actually dispatch, plus structured unknown-tool
+feedback when a proposed name is not part of that contract. There is no
+alias table and no argument-shape guessing here — a proposed tool name is
+either the exact canonical name (optionally normalized for case/separator
+formatting or an internal bridge prefix), or it is reported as unknown with
+discovery suggestions. It is intentionally execution-free: callers resolve a
+tool name here, then execute through their existing dispatch path.
 """
 
 from __future__ import annotations
@@ -11,7 +16,7 @@
 from dataclasses import dataclass, field
 from typing import Any, Dict, Literal, Mapping, Sequence
 
-ResolutionStatus = Literal["exact", "alias", "parameter_match", "unknown", "ambiguous"]
+ResolutionStatus = Literal["exact", "normalized", "unknown"]
 ResolutionConfidence = Literal["high", "medium", "low"]
 RiskLevel = Literal["read_only", "mutating", "external"]
 
@@ -40,36 +45,12 @@
     "delegate",
 )
 
-_DEFAULT_ALIASES: Mapping[str, str] = {
-    "list_dir": "file_list",
-    "list_directory": "file_list",
-    "list_files": "file_list",
-    "directory_list": "file_list",
-    "file_ls": "file_list",
-    "ls": "file_list",
-    "dir": "file_list",
-    "read_file": "file_read",
-    "open_file": "file_read",
-    "cat_file": "file_read",
-    "view_file": "file_read",
-    "write_file": "file_write",
-    "save_file": "file_write",
-    "search_text": "text_search",
-    "grep_text": "text_search",
-    "replace_text": "text_replace",
-    "execute_command": "shell_run",
-    "execute_shell": "shell_run",
-    "execute_shell_command": "shell_run",
-    "run_command": "shell_run",
-    "run_shell": "shell_run",
-    "shell": "shell_run",
-    "bash": "shell_run",
-    "terminal_command": "shell_run",
-}
-
+def tool_lookup_key(tool_name: str) -> str:
+    """Return a stable lookup key for exact tool-name identity matching.
 
-def tool_alias_key(tool_name: str) -> str:
-    """Return a stable lookup key for tool-name matching."""
+    This only normalizes formatting (case, hyphen/space vs underscore) of the
+    *same* canonical identifier. It never maps one tool name onto another.
+    """
     return tool_name.strip().lower().replace("-", "_").replace(" ", "_")
 
 
@@ -100,7 +81,7 @@ class ToolResolution:
     @property
     def is_resolved(self) -> bool:
         """Return whether the resolution has a canonical target."""
-        return self.normalized_name is not None and self.status not in {"unknown", "ambiguous"}
+        return self.normalized_name is not None and self.status != "unknown"
 
     def to_metadata(self) -> Dict[str, Any]:
         """Return compact metadata suitable for TUI logs and trace events."""
@@ -115,7 +96,7 @@ def to_metadata(self) -> Dict[str, Any]:
         if self.normalized_name is not None:
             metadata["normalized_tool_name"] = self.normalized_name
             if self.normalized_name != self.original_name:
-                metadata["alias"] = self.original_name
+                metadata["resolved_from"] = self.original_name
         if self.suggestions:
             metadata["tool_suggestions"] = list(self.suggestions)
         return metadata
@@ -123,10 +104,17 @@ def to_metadata(self) -> Dict[str, Any]:
 
 @dataclass(frozen=True)
 class ToolRegistry:
-    """Single source of truth for tool identity and resolution metadata."""
+    """Single source of truth for tool identity and resolution metadata.
+
+    The registry enforces a strict Tool Capability Contract: a proposed tool
+    name is only ever executed when it is the exact canonical name, or a
+    formatting-only variant of it (case, separators, or the internal ``gp_``
+    bridge prefix). There is no alias table and no argument-shape guessing;
+    anything else is reported as unknown so the caller can retry with an
+    exact name from the disclosed capability list.
+    """
 
     specs: Mapping[str, ToolSpec]
-    aliases: Mapping[str, str] = field(default_factory=dict)
 
     @classmethod
     def from_definitions(
@@ -135,7 +123,6 @@ def from_definitions(
         handlers: Mapping[str, Any],
         *,
         bridge_tools: Sequence[Mapping[str, Any]] = (),
-        aliases: Mapping[str, str] | None = None,
     ) -> "ToolRegistry":
         """Build a registry from OpenAI schemas, dispatch handlers, and bridge metadata."""
         bridge_mutates = {
@@ -165,13 +152,7 @@ def from_definitions(
                     name=canonical,
                     risk_level=_infer_risk_level(canonical, bridge_mutates.get(canonical, False)),
                 )
-        alias_source = aliases or _DEFAULT_ALIASES
-        normalized_aliases = {
-            tool_alias_key(alias): canonical
-            for alias, canonical in alias_source.items()
-            if canonical in specs
-        }
-        return cls(specs=specs, aliases=normalized_aliases)
+        return cls(specs=specs)
 
     @property
     def tool_names(self) -> tuple[str, ...]:
@@ -184,49 +165,16 @@ def normalize_name(self, tool_name: str, arguments: Mapping[str, Any] | None = N
         return resolution.normalized_name if resolution.auto_executable and resolution.normalized_name else tool_name
 
     def resolve(self, tool_name: str, arguments: Mapping[str, Any] | None = None) -> ToolResolution:
-        """Resolve a proposed tool call against canonical tool metadata."""
+        """Resolve a proposed tool call against the canonical tool contract."""
         original_name = str(tool_name or "")
         args = dict(arguments or {})
-        key = tool_alias_key(original_name)
+        key = tool_lookup_key(original_name)
         if original_name in self.specs:
             return self._resolution(original_name, original_name, "exact", "high", "canonical tool name")
         if key in self.specs:
-            canonical = key
-            return self._resolution(original_name, canonical, "alias", "high", "case or separator normalization")
+            return self._resolution(original_name, key, "normalized", "high", "case or separator normalization")
         if key.startswith("gp_") and key[3:] in self.specs:
-            canonical = key[3:]
-            return self._resolution(original_name, canonical, "alias", "high", "gp-prefixed bridge alias")
-        alias_target = self.aliases.get(key)
-        if alias_target:
-            return self._resolution(original_name, alias_target, "alias", "high", "declared tool alias")
-
-        parameter_candidates = self._parameter_candidates(original_name, args)
-        if len(parameter_candidates) == 1:
-            canonical, confidence, reason = parameter_candidates[0]
-            spec = self.specs[canonical]
-            auto = spec.risk_level == "read_only" and confidence in {"high", "medium"}
-            return ToolResolution(
-                original_name=original_name,
-                normalized_name=canonical,
-                status="parameter_match",
-                confidence=confidence,
-                reason=reason,
-                suggestions=(canonical,),
-                auto_executable=auto,
-                risk_level=spec.risk_level,
-            )
-        if len(parameter_candidates) > 1:
-            suggestions = tuple(candidate[0] for candidate in parameter_candidates[:5])
-            return ToolResolution(
-                original_name=original_name,
-                normalized_name=None,
-                status="ambiguous",
-                confidence="low",
-                reason="arguments match multiple tool shapes",
-                suggestions=suggestions,
-                auto_executable=False,
-                risk_level="read_only",
-            )
+            return self._resolution(original_name, key[3:], "normalized", "high", "internal bridge prefix")
 
         suggestions = self._suggestions(original_name, args)
         return ToolResolution(
@@ -234,16 +182,23 @@ def resolve(self, tool_name: str, arguments: Mapping[str, Any] | None = None) ->
             normalized_name=None,
             status="unknown",
             confidence="low",
-            reason="no canonical tool, alias, or safe parameter match",
+            reason="no exact canonical tool name match",
             suggestions=suggestions,
             auto_executable=False,
             risk_level="read_only",
         )
 
     def unknown_result(self, resolution: ToolResolution) -> Dict[str, Any]:
-        """Build structured feedback for unknown or ambiguous tool names."""
+        """Build structured feedback for an unresolved tool name."""
         available = self.tool_names[:16]
         suggestions = resolution.suggestions or available[:5]
+        recovery_hint = (
+            f"'{resolution.original_name}' is not a registered tool. Retry once with an exact "
+            f"name from: {', '.join(suggestions)}."
+            if suggestions
+            else f"'{resolution.original_name}' is not a registered tool and no close match was found; "
+            "ask for clarification instead of guessing."
+        )
         return {
             "ok": False,
             "error_type": "unknown_tool",
@@ -255,6 +210,7 @@ def unknown_result(self, resolution: ToolResolution) -> Dict[str, Any]:
             "resolution_reason": resolution.reason,
             "suggestions": list(suggestions),
             "available_tools": list(available),
+            "recovery_hint": recovery_hint,
             "retryable": True,
         }
 
@@ -267,7 +223,6 @@ def _resolution(
         reason: str,
     ) -> ToolResolution:
         spec = self.specs[canonical]
-        auto = confidence == "high" or spec.risk_level == "read_only"
         return ToolResolution(
             original_name=original_name,
             normalized_name=canonical,
@@ -275,34 +230,18 @@ def _resolution(
             confidence=confidence,
             reason=reason,
             suggestions=(canonical,) if canonical != original_name else (),
-            auto_executable=auto,
+            auto_executable=True,
             risk_level=spec.risk_level,
         )
 
-    def _parameter_candidates(
-        self, tool_name: str, arguments: Mapping[str, Any]) -> list[tuple[str, ResolutionConfidence, str]]:
-            keys = {str(key) for key in arguments.keys()}
-            name_key = tool_alias_key(tool_name)
-            candidates: list[tuple[str, ResolutionConfidence, str]] = []
-            if {"text", "old", "new"}.issubset(keys) and "text_replace" in self.specs:
-                candidates.append(("text_replace", "high", "text replacement argument shape"))
-            if {"text", "pattern"}.issubset(keys) and "text_search" in self.specs:
-                candidates.append(("text_search", "high", "text search argument shape"))
-            if "command" in keys and "shell_run" in self.specs:
-                confidence: ResolutionConfidence = "high" if any(token in name_key for token in ("shell", "command", "exec", "bash", "terminal")) else "medium"
-                candidates.append(("shell_run", confidence, "shell command argument shape"))
-            if "path" in keys:
-                if any(token in name_key for token in ("list", "dir", "directory", "ls", "files", "scan")) and "file_list" in self.specs:
-                    candidates.append(("file_list", "high", "directory listing argument shape"))
-                if any(token in name_key for token in ("read", "open", "view", "cat")) and "file_read" in self.specs:
-                    candidates.append(("file_read", "high", "file read argument shape"))
-                if "content" in keys and any(token in name_key for token in ("write", "save", "create")) and "file_write" in self.specs:
-                    candidates.append(("file_write", "high", "file write argument shape"))
-            return candidates
-
     def _suggestions(self, tool_name: str, arguments: Mapping[str, Any]) -> tuple[str, ...]:
+        """Return non-executing discovery hints for an unknown tool name.
+
+        These are surfaced to the caller for a retry with an exact name; they
+        are never used to auto-execute a different tool.
+        """
         names = list(self.tool_names)
-        close = difflib.get_close_matches(tool_alias_key(tool_name), names, n=5, cutoff=0.55)
+        close = difflib.get_close_matches(tool_lookup_key(tool_name), names, n=5, cutoff=0.55)
         if close:
             return tuple(close)
         keys = {str(key) for key in arguments.keys()}
diff --git a/src/leapflow/tools/registry_bootstrap.py b/src/leapflow/tools/registry_bootstrap.py
index 815ea77..0209eb4 100644
--- a/src/leapflow/tools/registry_bootstrap.py
+++ b/src/leapflow/tools/registry_bootstrap.py
@@ -53,7 +53,9 @@
             "description": (
                 "Read text file content with adaptive context governance. For large or unfamiliar files, "
                 "prefer mode='outline' or mode='symbols' first, then use mode='raw' "
-                "with start_line/max_lines for the specific range you actually need."
+                "with start_line/max_lines for the specific range you actually need. "
+                "Do not probe `<workspace>/.leapflow/config.json`; LeapFlow uses `~/.leapflow/.env` "
+                "and optional existing `./.env` project overrides."
             ),
             "parameters": {
                 "type": "object",
diff --git a/tests/test_agent_execution.py b/tests/test_agent_execution.py
index d5c0a2d..b1818c7 100644
--- a/tests/test_agent_execution.py
+++ b/tests/test_agent_execution.py
@@ -122,8 +122,8 @@ async def test_react_loop_tool_then_answer() -> None:
 
 
 @pytest.mark.asyncio
-async def test_tool_aliases_are_normalized_before_execution() -> None:
-    """Common LLM tool-name drift should route through canonical tool handlers."""
+async def test_exact_canonical_tool_names_execute_without_guessing() -> None:
+    """Only exact canonical tool names (plus case/separator formatting) execute."""
     with tempfile.TemporaryDirectory() as td:
         settings = make_settings(td)
         from leapflow.platform.mock import MockBridge
@@ -146,36 +146,37 @@ async def file_list_handler(args):
             engine._tool_bridge = None
 
             result = await engine._execute_general_tool(
-                {"name": "list_directory", "arguments": {"path": "."}},
+                {"name": "file_list", "arguments": {"path": "."}},
                 {"file_list": file_list_handler},
             )
             metadata = _tool_args_metadata(
                 "file_list",
                 {"path": "."},
-                original_tool_name="list_directory",
+                original_tool_name="File-List",
             )
 
             assert result["ok"] is True
             assert captured["args"] == {"path": "."}
-            assert _normalize_tool_name("list_directory") == "file_list"
-            assert _normalize_tool_name("List-Directory") == "file_list"
-            assert _normalize_tool_name("list files") == "file_list"
-            assert _normalize_tool_name("read_file") == "file_read"
-            assert _normalize_tool_name("write_file") == "file_write"
-            assert _normalize_tool_name("execute_command") == "shell_run"
-            assert _normalize_tool_name("execute shell command") == "shell_run"
-            assert _normalize_tool_name("terminal-command") == "shell_run"
+            # Case/separator formatting of the *same* canonical name still resolves.
+            assert _normalize_tool_name("File_List") == "file_list"
+            assert _normalize_tool_name("file-list") == "file_list"
+            # Common LLM tool-name drift is no longer silently rewritten to a
+            # different canonical tool: it must be reported as unknown.
+            assert _normalize_tool_name("list_directory") == "list_directory"
+            assert _normalize_tool_name("execute_command") == "execute_command"
+            assert _normalize_tool_name("run_terminal") == "run_terminal"
             directory_resolution = _resolve_tool_name("directory_scan", {"path": "."})
             risky_resolution = _resolve_tool_name("please_do", {"command": "ls -la"})
-            assert directory_resolution.normalized_name == "file_list"
-            assert directory_resolution.status == "parameter_match"
-            assert directory_resolution.auto_executable is True
-            assert risky_resolution.normalized_name == "shell_run"
-            assert risky_resolution.status == "parameter_match"
+            assert directory_resolution.normalized_name is None
+            assert directory_resolution.status == "unknown"
+            assert directory_resolution.auto_executable is False
+            assert risky_resolution.normalized_name is None
+            assert risky_resolution.status == "unknown"
             assert risky_resolution.auto_executable is False
-            assert metadata["original_tool_name"] == "list_directory"
+            assert metadata["original_tool_name"] == "File-List"
             assert metadata["normalized_tool_name"] == "file_list"
-            assert metadata["alias"] == "list_directory"
+            assert metadata["resolved_from"] == "File-List"
+            assert "alias" not in metadata
         finally:
             lt.close()
 
@@ -253,8 +254,133 @@ async def achat(self, messages, *, stream=True, enable_thinking=False, **kwargs)
             lt.close()
 
 @pytest.mark.asyncio
-async def test_text_tool_alias_is_normalized_in_stream_events() -> None:
-    """Text-mode tool calls should not leak common alias names as unknown tools."""
+async def test_app_connector_context_is_injected_without_extra_llm_call() -> None:
+    class CaptureLLM(StubLLM):
+        def __init__(self) -> None:
+            super().__init__(["Use platform_connect for supported app onboarding."])
+            self.seen_messages: list[list[dict[str, object]]] = []
+
+        async def achat(self, messages, *, stream=True, enable_thinking=False, **kwargs):
+            self.seen_messages.append(list(messages))
+            return await super().achat(messages, stream=stream, enable_thinking=enable_thinking, **kwargs)
+
+    with tempfile.TemporaryDirectory() as td:
+        settings = make_settings(td)
+        from leapflow.gateway.server import GatewayServer
+        from leapflow.platform.mock import MockBridge
+        from leapflow.tools.gateway_tool import set_gateway_approval_gate, set_gateway_server
+
+        rpc = MockBridge()
+        llm = CaptureLLM()
+        wm = WorkingMemoryProvider(max_tokens=1024)
+        lt = SemanticMemoryProvider(source=settings.duckdb_path)
+        imm = EpisodicMemoryProvider()
+        server = GatewayServer(settings.profile_dir)
+        server.discover_manifests()
+        set_gateway_server(server)
+        set_gateway_approval_gate(None)
+        try:
+            reg = build_default_registry(rpc, llm, wm, lt)
+            classifier = _FixedClassifier("complex")
+            engine = AgentEngine(settings, rpc, llm, wm, lt, imm, reg, classifier)
+
+            out = await engine.run("接入飞书")
+
+            system_prompt = str(llm.seen_messages[0][0].get("content", ""))
+            assert out == "Use platform_connect for supported app onboarding."
+            assert "App Connector Capability Index" in system_prompt
+            assert "`feishu`" in system_prompt
+            assert "`telegram`" in system_prompt
+            assert "platform_connect" in system_prompt
+            assert llm.call_count == 1
+        finally:
+            await server.stop()
+            set_gateway_approval_gate(None)
+            set_gateway_server(None)
+            lt.close()
+
+
+@pytest.mark.asyncio
+async def test_app_connector_llm_tool_call_uses_same_unified_loop() -> None:
+    tool_reply = '<tool_call>{"name": "platform_connect", "arguments": {"action": "guide", "platform": "telegram"}}</tool_call>'
+    with tempfile.TemporaryDirectory() as td:
+        settings = make_settings(td)
+        from leapflow.gateway.server import GatewayServer
+        from leapflow.platform.mock import MockBridge
+        from leapflow.tools.gateway_tool import set_gateway_approval_gate, set_gateway_server
+
+        rpc = MockBridge()
+        llm = StubLLM([tool_reply, "Telegram guide ready"])
+        wm = WorkingMemoryProvider(max_tokens=1024)
+        lt = SemanticMemoryProvider(source=settings.duckdb_path)
+        imm = EpisodicMemoryProvider()
+        server = GatewayServer(settings.profile_dir)
+        server.discover_manifests()
+        set_gateway_server(server)
+        set_gateway_approval_gate(None)
+        try:
+            reg = build_default_registry(rpc, llm, wm, lt)
+            classifier = _FixedClassifier("complex")
+            engine = AgentEngine(settings, rpc, llm, wm, lt, imm, reg, classifier)
+
+            events = [event async for event in engine.run_stream("配置 Telegram")]
+
+            tool_events = [event for event in events if event.type in {"tool_start", "tool_complete"}]
+            assert [event.content for event in tool_events] == ["platform_connect", "platform_connect"]
+            assert tool_events[1].metadata["ok"] is True
+            assert events[-1].type == "final"
+            assert "Telegram guide ready" in events[-1].content
+            assert llm.call_count == 2
+        finally:
+            await server.stop()
+            set_gateway_approval_gate(None)
+            set_gateway_server(None)
+            lt.close()
+
+
+@pytest.mark.asyncio
+async def test_app_connector_empty_final_uses_onboarding_recovery_state() -> None:
+    tool_reply = (
+        '<tool_call>{"name": "platform_connect", "arguments": '
+        '{"action": "guide", "platform": "feishu", '
+        '"options": {"binary": "definitely-missing-cli-for-onboarding-test"}}}</tool_call>'
+    )
+    with tempfile.TemporaryDirectory() as td:
+        settings = make_settings(td)
+        from leapflow.gateway.server import GatewayServer
+        from leapflow.platform.mock import MockBridge
+        from leapflow.tools.gateway_tool import set_gateway_approval_gate, set_gateway_server
+
+        rpc = MockBridge()
+        llm = StubLLM([tool_reply, ""])
+        wm = WorkingMemoryProvider(max_tokens=1024)
+        lt = SemanticMemoryProvider(source=settings.duckdb_path)
+        imm = EpisodicMemoryProvider()
+        server = GatewayServer(settings.profile_dir)
+        server.discover_manifests()
+        set_gateway_server(server)
+        set_gateway_approval_gate(None)
+        try:
+            reg = build_default_registry(rpc, llm, wm, lt)
+            classifier = _FixedClassifier("complex")
+            engine = AgentEngine(settings, rpc, llm, wm, lt, imm, reg, classifier)
+
+            final = await engine.run("继续接入")
+        finally:
+            await server.stop()
+            set_gateway_approval_gate(None)
+            set_gateway_server(None)
+            lt.close()
+
+    assert llm.call_count == 2
+    assert "App onboarding is paused" in final
+    assert "cli_missing" in final
+    assert "definitely-missing-cli-for-onboarding-test" in final
+
+
+@pytest.mark.asyncio
+async def test_unknown_tool_in_stream_triggers_structured_retry_not_alias_guess() -> None:
+    """Text-mode tool calls with a drifted name must surface a structured unknown, never a silent alias rewrite."""
     tool_reply = '<tool_call>{"name": "list_directory", "arguments": {"path": "."}}</tool_call>'
     with tempfile.TemporaryDirectory() as td:
         settings = make_settings(td)
@@ -273,11 +399,12 @@ async def test_text_tool_alias_is_normalized_in_stream_events() -> None:
             events = [event async for event in engine.run_stream("List current directory")]
 
             tool_events = [event for event in events if event.type in {"tool_start", "tool_complete"}]
-            assert [event.content for event in tool_events] == ["file_list", "file_list"]
+            assert [event.content for event in tool_events] == ["list_directory", "list_directory"]
             assert tool_events[0].metadata["original_tool_name"] == "list_directory"
-            assert tool_events[0].metadata["normalized_tool_name"] == "file_list"
-            assert tool_events[1].metadata["ok"] is True
-            assert "Unknown tool" not in str(tool_events[1].metadata)
+            assert tool_events[0].metadata["tool_resolution_status"] == "unknown"
+            assert tool_events[1].metadata["ok"] is False
+            assert tool_events[1].metadata["error_type"] == "unknown_tool"
+            assert "resolved_from" not in tool_events[1].metadata
         finally:
             lt.close()
 
@@ -464,6 +591,9 @@ async def achat_stream(self, messages, *, enable_thinking=False, **kwargs):
             assert "Original user request: hello" in system_prompt
             assert "Workspace root:" in system_prompt
             assert "never infer `.` as the project root" in system_prompt
+            assert "do not probe that path" in system_prompt
+            assert "~/.leapflow/.env" in system_prompt
+            assert "./.env" in system_prompt
             snapshot = engine.context_budget_snapshot
             assert snapshot["disclosure_level"] == "light"
             assert snapshot["disclosure"]["native_tools"] is False
@@ -704,3 +834,95 @@ def test_task_graph_retry_policy() -> None:
     assert node.status == TaskStatus.FAILED
     assert node.attempt_count == 3
     assert node.error == "permanent error"
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Idempotency guard and failure recovery tests
+# ═══════════════════════════════════════════════════════════════════
+
+
+def test_platform_action_fingerprint_deduplicates_identical_calls() -> None:
+    """_platform_action_fingerprint returns the same key for identical calls."""
+    from leapflow.engine.engine import _platform_action_fingerprint
+
+    fp1 = _platform_action_fingerprint(
+        "platform_action",
+        {"platform": "feishu", "action": "im.send_message", "payload": {"chat_id": "oc_1", "text": "hi"}},
+    )
+    fp2 = _platform_action_fingerprint(
+        "platform_action",
+        {"platform": "feishu", "action": "im.send_message", "payload": {"chat_id": "oc_1", "text": "hi"}},
+    )
+    fp_different = _platform_action_fingerprint(
+        "platform_action",
+        {"platform": "feishu", "action": "im.send_message", "payload": {"chat_id": "oc_2", "text": "hi"}},
+    )
+    fp_read = _platform_action_fingerprint(
+        "platform_action",
+        {"platform": "feishu", "action": "im.search_chats", "payload": {"query": "LeapFlow"}},
+    )
+    fp_other_tool = _platform_action_fingerprint(
+        "file_list",
+        {"path": "."},
+    )
+
+    assert fp1 is not None
+    assert fp1 == fp2, "Identical calls must produce the same fingerprint"
+    assert fp1 != fp_different, "Different payload must produce a different fingerprint"
+    assert fp_read is not None, "Read platform_actions are also fingerprinted (dedup applies)"
+    assert fp_other_tool is None, "Non-platform_action tools must return None"
+
+
+def test_last_tool_failures_recovery_message_from_unknown_action() -> None:
+    """_last_tool_failures_recovery_message extracts context from unknown_platform_action results."""
+    import json
+    from leapflow.engine.engine import _last_tool_failures_recovery_message
+
+    failure_payload = {
+        "ok": False,
+        "failure_code": "unknown_platform_action",
+        "error": "Unknown platform action: feishu.im.chat.list",
+        "platform": "feishu",
+        "requested_action": "im.chat.list",
+        "available_action_names": ["im.send_message", "im.list_chats", "im.search_chats"],
+        "recovery_hint": "Use exactly one registered action name from available_action_names.",
+        "retryable": True,
+    }
+    messages = [
+        {"role": "tool", "content": json.dumps(failure_payload)},
+    ]
+    result = _last_tool_failures_recovery_message(messages)
+
+    assert result, "Should produce non-empty recovery message"
+    assert "feishu.im.chat.list" in result or "im.chat.list" in result
+    assert "im.list_chats" in result
+    assert "im.send_message" in result
+
+
+def test_last_tool_failures_recovery_message_missing_fields() -> None:
+    """_last_tool_failures_recovery_message handles Missing required fields errors."""
+    import json
+    from leapflow.engine.engine import _last_tool_failures_recovery_message
+
+    failure_payload = {
+        "ok": False,
+        "error": "Missing required fields: text",
+    }
+    messages = [{"role": "tool", "content": json.dumps(failure_payload)}]
+    result = _last_tool_failures_recovery_message(messages)
+
+    assert result
+    assert "text" in result
+
+
+def test_last_tool_failures_recovery_message_returns_empty_when_no_failures() -> None:
+    """Returns empty string when there are no failed tool results in history."""
+    import json
+    from leapflow.engine.engine import _last_tool_failures_recovery_message
+
+    messages = [
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "sure"},
+        {"role": "tool", "content": json.dumps({"ok": True, "data": {}})},
+    ]
+    assert _last_tool_failures_recovery_message(messages) == ""
diff --git a/tests/test_app_connector.py b/tests/test_app_connector.py
new file mode 100644
index 0000000..331cde8
--- /dev/null
+++ b/tests/test_app_connector.py
@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import pytest
+
+from leapflow.gateway.adapters.feishu import FeishuAdapter
+from leapflow.gateway.connectors.action_registry import ActionRegistry
+from leapflow.gateway.connectors.protocol import ActionPreview, ActionResult, BackendStatus
+
+
+class FakeBackend:
+    kind = "cli"
+
+    async def status(self) -> BackendStatus:
+        return BackendStatus(ok=True, backend_kind=self.kind)
+
+    async def authenticate(self, payload) -> BackendStatus:
+        return BackendStatus(ok=True, backend_kind=self.kind, metadata=dict(payload))
+
+    async def execute(self, spec, payload) -> ActionResult:
+        return ActionResult(ok=True, resource_id=spec.name, data=dict(payload))
+
+    async def preview(self, spec, payload) -> ActionPreview:
+        return ActionPreview(ok=True, summary=f"preview {spec.name}")
+
+
+@pytest.mark.asyncio
+async def test_feishu_adapter_exposes_app_connector_actions() -> None:
+    adapter = FeishuAdapter(backend=FakeBackend())
+
+    specs = adapter.action_specs()
+    result = await adapter.execute_action(
+        "im.send_message",
+        {"chat_id": "oc_1", "text": "hello"},
+    )
+
+    assert "im.send_message" in specs
+    assert "docs.create_markdown" in specs
+    assert "calendar.create_event" in specs
+    assert "mail.search_unread" in specs
+    assert result.ok is True
+    assert result.resource_id == "im.send_message"
+
+
+@pytest.mark.asyncio
+async def test_feishu_adapter_rejects_unknown_action() -> None:
+    adapter = FeishuAdapter(backend=FakeBackend())
+
+    result = await adapter.execute_action("docs.unknown", {})
+
+    assert result.ok is False
+    assert "Unknown Feishu action" in result.error
+
+
+@pytest.mark.asyncio
+async def test_feishu_adapter_validates_registered_action_schema() -> None:
+    adapter = FeishuAdapter(backend=FakeBackend())
+
+    missing = await adapter.execute_action("docs.create_markdown", {"title": "Doc"})
+    wrong_type = await adapter.execute_action(
+        "sheets.append_row",
+        {"spreadsheet_token": "s", "sheet_id": "sid", "values": "not-array"},
+    )
+
+    assert missing.ok is False
+    assert "Missing required fields: markdown" in missing.error
+    assert wrong_type.ok is False
+    assert "values" in wrong_type.error
+
+
+@pytest.mark.asyncio
+async def test_feishu_adapter_returns_cli_preview() -> None:
+    adapter = FeishuAdapter(profile="bot-reader", backend=FakeBackend())
+
+    preview = await adapter.preview_action(
+        "im.send_message",
+        {"chat_id": "oc_1", "text": "hello"},
+    )
+
+    assert preview.ok is True
+    assert preview.summary == "preview im.send_message"
+
+
+def test_action_registry_loads_standard_action_pack_export() -> None:
+    registry = ActionRegistry.from_module("leapflow.gateway.action_packs.feishu")
+
+    assert registry.get("im.send_message") is not None
+    assert registry.get("task.create") is not None
diff --git a/tests/test_approval_layer.py b/tests/test_approval_layer.py
index 2a653e1..9c3f23e 100644
--- a/tests/test_approval_layer.py
+++ b/tests/test_approval_layer.py
@@ -64,6 +64,23 @@ def test_default_risk_classifier_detects_heredoc() -> None:
     assert risk.allow_permanent is False
 
 
+def test_platform_action_risk_uses_registered_metadata() -> None:
+    action = ActionDescriptor.platform_action(
+        "feishu",
+        "mail.search_unread",
+        {"query": "urgent"},
+        backend_kind="cli",
+        metadata={"effect": "read", "risk_level": "high"},
+    )
+
+    risk = DefaultRiskClassifier().assess(action)
+
+    assert risk.level == RiskLevel.HIGH
+    assert risk.reasons == ("registered_platform_action",)
+    assert risk.allow_permanent is False
+    assert risk.metadata["backend_kind"] == "cli"
+
+
 def test_approval_request_round_trips_request_id() -> None:
     from leapflow.security.approval import ApprovalRequest
 
diff --git a/tests/test_cli_discovery.py b/tests/test_cli_discovery.py
new file mode 100644
index 0000000..b5f131a
--- /dev/null
+++ b/tests/test_cli_discovery.py
@@ -0,0 +1,513 @@
+"""Tests for CLI help-based command discovery."""
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from leapflow.gateway.connectors.cli_discovery import (
+    CliDiscovery,
+    DiscoveredCommand,
+    HelpArgument,
+    HelpParser,
+    _action_name,
+    _build_argv_template,
+    _build_schema,
+    _infer_effect,
+)
+from leapflow.gateway.connectors.action_registry import ActionRegistry
+from leapflow.gateway.connectors.protocol import ActionSpec, BackendKind
+
+
+# ── Realistic help text fixtures ─────────────────────────────────────
+
+CLICK_TOP_LEVEL_HELP = """\
+Usage: lark-cli [OPTIONS] COMMAND [ARGS]...
+
+  Official Feishu/Lark CLI tool.
+
+Options:
+  --profile TEXT  Profile name
+  --as TEXT       Identity (bot or user)
+  --help          Show this message and exit.
+
+Commands:
+  auth       Manage authentication
+  im         Instant messaging operations
+  docs       Document management
+  calendar   Calendar event management
+  drive      Cloud drive operations
+  task       Task management
+  mail       Mail operations
+"""
+
+CLICK_GROUP_HELP = """\
+Usage: lark-cli im [OPTIONS] COMMAND [ARGS]...
+
+  Instant messaging operations for Feishu/Lark.
+
+Commands:
+  +messages-send    Send a message to a chat
+  +messages-list    List messages in a chat
+  +chat-list        List chats the bot is in
+  +chat-search      Search chats by keyword
+  +chat-create      Create a new group chat
+"""
+
+CLICK_COMMAND_HELP = """\
+Usage: lark-cli im +messages-send [OPTIONS]
+
+  Send a text message to a Feishu/Lark chat.
+
+Options:
+  --chat-id TEXT     Target chat ID (required)
+  --text TEXT        Message content (required)
+  --thread-id TEXT   Optional thread for replies
+  --dry-run          Preview without sending
+  --help             Show this message and exit.
+"""
+
+COBRA_HELP = """\
+Manage Kubernetes resources
+
+Usage:
+  kubectl get [resource] [flags]
+
+Flags:
+  -o, --output string     Output format (json|yaml|wide)
+  -n, --namespace string  Namespace scope (required)
+  -l, --selector string   Label selector
+      --all-namespaces     List across all namespaces
+  -h, --help              help for get
+"""
+
+ARGPARSE_HELP = """\
+usage: mytool [-h] {send,list,delete} ...
+
+My CLI tool for managing resources.
+
+positional arguments:
+  {send,list,delete}
+    send              Send a notification
+    list              List all items
+    delete            Delete an item
+
+options:
+  -h, --help          show this help message and exit
+"""
+
+MINIMAL_HELP = """\
+Usage: simple-tool [command]
+
+Commands:
+  run     Execute the main task
+  check   Verify configuration
+"""
+
+
+# ── HelpParser tests ─────────────────────────────────────────────────
+
+class TestHelpParser:
+
+    def test_parse_click_top_level(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(CLICK_TOP_LEVEL_HELP, binary="lark-cli")
+
+        assert result.binary == "lark-cli"
+        assert len(result.subcommands) == 7
+        names = [cmd.name for cmd in result.subcommands]
+        assert "im" in names
+        assert "docs" in names
+        assert "calendar" in names
+        assert result.subcommands[1].name == "im"
+        assert "messaging" in result.subcommands[1].description.lower()
+
+    def test_parse_click_group(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(CLICK_GROUP_HELP, binary="lark-cli", prefix=["im"])
+
+        assert result.prefix == ("im",)
+        assert len(result.subcommands) == 5
+        names = [cmd.name for cmd in result.subcommands]
+        assert "+messages-send" in names
+        assert "+chat-search" in names
+
+    def test_parse_click_command_arguments(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(
+            CLICK_COMMAND_HELP,
+            binary="lark-cli",
+            prefix=["im", "+messages-send"],
+        )
+
+        assert len(result.arguments) >= 3
+        arg_names = [a.name for a in result.arguments]
+        assert "chat_id" in arg_names
+        assert "text" in arg_names
+        assert "thread_id" in arg_names
+
+        chat_id = next(a for a in result.arguments if a.name == "chat_id")
+        assert chat_id.flag == "--chat-id"
+        assert chat_id.required is True
+
+    def test_parse_cobra_flags(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(COBRA_HELP, binary="kubectl", prefix=["get"])
+
+        assert len(result.arguments) >= 3
+        ns = next((a for a in result.arguments if a.name == "namespace"), None)
+        assert ns is not None
+        assert ns.flag == "--namespace"
+        assert ns.required is True
+
+    def test_parse_argparse_subcommands(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(ARGPARSE_HELP, binary="mytool")
+
+        assert len(result.subcommands) == 3
+        names = [cmd.name for cmd in result.subcommands]
+        assert "send" in names
+        assert "delete" in names
+
+    def test_parse_minimal_help(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(MINIMAL_HELP, binary="simple-tool")
+
+        assert len(result.subcommands) == 2
+        assert result.subcommands[0].name == "run"
+
+    def test_parse_empty_help(self) -> None:
+        parser = HelpParser()
+        result = parser.parse("", binary="empty")
+
+        assert result.subcommands == ()
+        assert result.arguments == ()
+
+    def test_description_extraction(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(CLICK_TOP_LEVEL_HELP, binary="lark-cli")
+
+        assert "official" in result.description.lower() or "feishu" in result.description.lower()
+
+    def test_help_and_version_flags_excluded(self) -> None:
+        parser = HelpParser()
+        result = parser.parse(CLICK_COMMAND_HELP, binary="lark-cli")
+
+        flag_names = [a.flag for a in result.arguments]
+        assert "--help" not in flag_names
+        assert "--version" not in flag_names
+
+
+    def test_parse_subcommands_across_blank_lines(self) -> None:
+        help_text = """\
+Usage: demo [OPTIONS] COMMAND [ARGS]...
+
+Commands:
+  first     First command
+
+  second    Second command after a blank line
+  third     Third command
+"""
+        parser = HelpParser()
+        result = parser.parse(help_text, binary="demo")
+
+        assert [cmd.name for cmd in result.subcommands] == ["first", "second", "third"]
+
+    def test_parse_arguments_across_blank_lines(self) -> None:
+        help_text = """\
+Usage: demo send [OPTIONS]
+
+Options:
+  --chat-id TEXT  Target chat (required)
+
+  --text TEXT     Message text (required)
+  --dry-run       Preview only
+"""
+        parser = HelpParser()
+        result = parser.parse(help_text, binary="demo", prefix=["send"])
+
+        assert [arg.name for arg in result.arguments] == ["chat_id", "text", "dry_run"]
+
+
+# ── DiscoveredCommand → ActionSpec builders ──────────────────────────
+
+class TestSpecBuilders:
+
+    def test_action_name_two_level(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="lark-cli",
+            argv_prefix=("im", "+messages-send"),
+            group="im",
+        )
+        assert _action_name(cmd) == "im.messages_send"
+
+    def test_action_name_with_domain(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="lark-cli",
+            argv_prefix=("im", "+messages-send"),
+        )
+        assert _action_name(cmd, domain="messaging") == "messaging.messages_send"
+
+    def test_action_name_single_level(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="tool",
+            argv_prefix=("status",),
+        )
+        assert _action_name(cmd) == "status.status"
+
+    def test_build_argv_template(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="lark-cli",
+            argv_prefix=("im", "+messages-send"),
+            arguments=(
+                HelpArgument(name="chat_id", flag="--chat-id", required=True),
+                HelpArgument(name="text", flag="--text", required=True),
+                HelpArgument(name="thread_id", flag="--thread-id", required=False),
+            ),
+        )
+        template = _build_argv_template(cmd)
+        assert template == ["im", "+messages-send", "--chat-id", "{chat_id}", "--text", "{text}"]
+
+    def test_build_schema(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="lark-cli",
+            argv_prefix=("im", "+send"),
+            arguments=(
+                HelpArgument(name="chat_id", flag="--chat-id", required=True, description="Target chat"),
+                HelpArgument(name="limit", flag="--limit", type_hint="integer"),
+            ),
+        )
+        schema = _build_schema(cmd)
+        assert schema["required"] == ["chat_id"]
+        assert "chat_id" in schema["properties"]
+        assert schema["properties"]["limit"]["type"] == "integer"
+
+    def test_infer_effect_from_command_name(self) -> None:
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("list",))) == "read"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("send",))) == "send"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("create",))) == "write"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("delete",))) == "execute"
+
+    def test_infer_effect_word_boundary_avoids_false_positives(self) -> None:
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("reset",))) == "execute"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("unset",))) == "execute"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("forget",))) == "execute"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("offset",))) == "execute"
+
+    def test_infer_effect_matches_hyphenated_commands(self) -> None:
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("im", "+messages-send"))) == "send"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("im", "+chat-list"))) == "read"
+        assert _infer_effect(DiscoveredCommand(binary="t", argv_prefix=("admin", "force-delete"))) == "execute"
+
+    def test_infer_effect_from_description(self) -> None:
+        cmd = DiscoveredCommand(
+            binary="t",
+            argv_prefix=("do-thing",),
+            description="Search for items in the database",
+        )
+        assert _infer_effect(cmd) == "read"
+
+
+# ── CliDiscovery async tests ─────────────────────────────────────────
+
+class TestCliDiscovery:
+
+    @pytest.mark.asyncio
+    async def test_discover_parses_help_output(self) -> None:
+        discovery = CliDiscovery(binary="lark-cli")
+        with patch.object(discovery, "_run_help", return_value=CLICK_TOP_LEVEL_HELP):
+            result = await discovery.discover()
+
+        assert result.binary == "lark-cli"
+        assert len(result.subcommands) == 7
+
+    @pytest.mark.asyncio
+    async def test_discover_group_builds_commands(self) -> None:
+        discovery = CliDiscovery(binary="lark-cli")
+
+        async def fake_run_help(argv):
+            if argv[-2:] == ["im", "--help"] or "im" in argv and "--help" in argv and "+messages" not in " ".join(argv):
+                return CLICK_GROUP_HELP
+            return CLICK_COMMAND_HELP
+
+        with patch.object(discovery, "_run_help", side_effect=fake_run_help):
+            commands = await discovery.discover_group("im")
+
+        assert len(commands) == 5
+        send_cmd = next(c for c in commands if "+messages-send" in c.argv_prefix)
+        assert send_cmd.group == "im"
+        assert send_cmd.depth == 2
+        assert len(send_cmd.arguments) >= 3
+
+    @pytest.mark.asyncio
+    async def test_to_action_spec_defaults_high_risk(self) -> None:
+        discovery = CliDiscovery(binary="lark-cli")
+        cmd = DiscoveredCommand(
+            binary="lark-cli",
+            argv_prefix=("im", "+messages-send"),
+            description="Send a message to a chat",
+            arguments=(
+                HelpArgument(name="chat_id", flag="--chat-id", required=True),
+                HelpArgument(name="text", flag="--text", required=True),
+            ),
+            group="im",
+        )
+
+        spec = discovery.to_action_spec(cmd)
+
+        assert spec.backend_kind == "cli"
+        assert spec.risk_level == "high"
+        assert spec.effect == "send"
+        assert spec.backend_config["discovered"] is True
+        assert "chat_id" in spec.schema.get("required", [])
+        argv = spec.backend_config["argv"]
+        assert list(argv) == ["im", "+messages-send", "--chat-id", "{chat_id}", "--text", "{text}"]
+
+    @pytest.mark.asyncio
+    async def test_to_action_spec_dangerous_command_is_critical(self) -> None:
+        discovery = CliDiscovery(binary="tool")
+        cmd = DiscoveredCommand(
+            binary="tool",
+            argv_prefix=("admin", "delete-all"),
+            description="Delete all resources permanently",
+        )
+
+        spec = discovery.to_action_spec(cmd)
+
+        assert spec.risk_level == "critical"
+
+    @pytest.mark.asyncio
+    async def test_cache_avoids_repeated_help_calls(self) -> None:
+        discovery = CliDiscovery(binary="lark-cli", cache_ttl_s=60.0)
+        call_count = 0
+
+        async def counting_run_help(argv):
+            nonlocal call_count
+            call_count += 1
+            return CLICK_TOP_LEVEL_HELP
+
+        with patch.object(discovery, "_run_help", side_effect=counting_run_help):
+            await discovery.discover()
+            await discovery.discover()
+            await discovery.discover()
+
+        assert call_count == 1
+
+    @pytest.mark.asyncio
+    async def test_invalidate_clears_cache(self) -> None:
+        discovery = CliDiscovery(binary="lark-cli", cache_ttl_s=60.0)
+        call_count = 0
+
+        async def counting_run_help(argv):
+            nonlocal call_count
+            call_count += 1
+            return CLICK_TOP_LEVEL_HELP
+
+        with patch.object(discovery, "_run_help", side_effect=counting_run_help):
+            await discovery.discover()
+            discovery.invalidate()
+            await discovery.discover()
+
+        assert call_count == 2
+
+
+# ── ActionRegistry + discovery integration ───────────────────────────
+
+class TestRegistryDiscovery:
+
+    def test_merge_discovered_does_not_overwrite_static(self) -> None:
+        static_spec = ActionSpec(
+            name="im.send_message",
+            backend_kind="cli",
+            description="Static verified spec",
+            risk_level="high",
+        )
+        registry = ActionRegistry({"im.send_message": static_spec})
+
+        discovered_spec = ActionSpec(
+            name="im.send_message",
+            backend_kind="cli",
+            description="Discovered draft spec",
+            risk_level="high",
+        )
+        added = registry.merge_discovered([discovered_spec])
+
+        assert added == 0
+        assert registry.get("im.send_message") is static_spec
+        assert not registry.is_discovered("im.send_message")
+
+    def test_merge_discovered_adds_new_specs(self) -> None:
+        static_spec = ActionSpec(
+            name="im.send_message",
+            backend_kind="cli",
+        )
+        registry = ActionRegistry({"im.send_message": static_spec})
+
+        new_spec = ActionSpec(
+            name="calendar.create_event",
+            backend_kind="cli",
+            description="Discovered via --help",
+        )
+        added = registry.merge_discovered([new_spec])
+
+        assert added == 1
+        assert registry.get("calendar.create_event") is new_spec
+        assert registry.is_discovered("calendar.create_event")
+
+    def test_all_returns_merged_specs(self) -> None:
+        static = ActionSpec(name="im.send", backend_kind="cli")
+        discovered = ActionSpec(name="docs.create", backend_kind="cli")
+        registry = ActionRegistry({"im.send": static})
+        registry.merge_discovered([discovered])
+
+        all_specs = registry.all()
+
+        assert "im.send" in all_specs
+        assert "docs.create" in all_specs
+        assert all_specs["im.send"] is static
+
+    def test_static_and_discovered_specs_separated(self) -> None:
+        static = ActionSpec(name="im.send", backend_kind="cli")
+        discovered = ActionSpec(name="docs.create", backend_kind="cli")
+        registry = ActionRegistry({"im.send": static})
+        registry.merge_discovered([discovered])
+
+        assert "im.send" in registry.static_specs()
+        assert "im.send" not in registry.discovered_specs()
+        assert "docs.create" in registry.discovered_specs()
+        assert "docs.create" not in registry.static_specs()
+
+    @pytest.mark.asyncio
+    async def test_refresh_discovery_uses_attached_source(self) -> None:
+        discovered_spec = ActionSpec(
+            name="task.list",
+            backend_kind="cli",
+            description="List tasks",
+        )
+
+        class FakeDiscovery:
+            async def discover_actions(self, *, groups=()):
+                return [discovered_spec]
+
+        registry = ActionRegistry({}, discovery=FakeDiscovery())
+        added = await registry.refresh_discovery()
+
+        assert added == 1
+        assert registry.get("task.list") is discovered_spec
+
+    @pytest.mark.asyncio
+    async def test_refresh_discovery_without_source_returns_zero(self) -> None:
+        registry = ActionRegistry({})
+        added = await registry.refresh_discovery()
+        assert added == 0
+
+    @pytest.mark.asyncio
+    async def test_refresh_discovery_error_is_swallowed(self) -> None:
+        class FailingDiscovery:
+            async def discover_actions(self, *, groups=()):
+                raise RuntimeError("network error")
+
+        registry = ActionRegistry({}, discovery=FailingDiscovery())
+        added = await registry.refresh_discovery()
+        assert added == 0
diff --git a/tests/test_context_disclosure.py b/tests/test_context_disclosure.py
index 91b52b7..f848312 100644
--- a/tests/test_context_disclosure.py
+++ b/tests/test_context_disclosure.py
@@ -132,3 +132,15 @@ def test_capability_manifest_prefers_explicit_tool_metadata() -> None:
     assert manifest.input_signals == ("alert", "notify")
     assert manifest.requires_approval is True
     assert manifest.schema_cost == "high"
+
+
+def test_file_read_schema_discourages_workspace_config_probe() -> None:
+    file_read_def = next(
+        item for item in TOOL_DEFINITIONS
+        if item.get("function", {}).get("name") == "file_read"
+    )
+    description = str(file_read_def["function"].get("description", ""))
+
+    assert "Do not probe `<workspace>/.leapflow/config.json`" in description
+    assert "~/.leapflow/.env" in description
+    assert "./.env" in description
diff --git a/tests/test_context_governance.py b/tests/test_context_governance.py
index 9efb74c..119fd26 100644
--- a/tests/test_context_governance.py
+++ b/tests/test_context_governance.py
@@ -4,7 +4,13 @@
 
 import pytest
 
-from leapflow.engine.context_compressor import CompressorConfig, ContextCompressor
+from leapflow.engine.context_compressor import (
+    CompressorConfig,
+    ContextCompressor,
+    SummarizeStage,
+    adaptive_trim_chars,
+    estimate_text_tokens,
+)
 from leapflow.engine.context_control import (
     ContextBudgetEstimator,
     ContextGovernanceController,
@@ -34,6 +40,27 @@ def test_context_estimator_counts_messages_and_tool_schemas() -> None:
     assert 0 < snapshot.ratio < 1
 
 
+def test_context_compressor_tolerates_none_tool_calls() -> None:
+    compressor = ContextCompressor(CompressorConfig(
+        token_budget=100,
+        token_count_fn=lambda text: len(str(text)),
+    ))
+    messages = [
+        {"role": "assistant", "content": "plain response", "tool_calls": None},
+        {"role": "user", "content": "next request"},
+    ]
+
+    formatted = SummarizeStage._format_turns_for_summary(messages)
+    summary = SummarizeStage._deterministic_summary(messages)
+    sanitized = SummarizeStage._sanitize_tool_pairs(messages)
+    token_count = compressor._count_tokens(messages)
+
+    assert "plain response" in formatted
+    assert "next request" in summary
+    assert sanitized == messages
+    assert token_count > 0
+
+
 def test_context_window_controller_forces_final_answer_when_over_budget() -> None:
     controller = ContextWindowController(
         estimator=ContextBudgetEstimator(),
@@ -154,6 +181,17 @@ def test_long_task_metadata_avoids_noise_for_uncompacted_tools() -> None:
     assert metadata == {}
 
 
+@pytest.mark.asyncio
+async def test_file_read_rejects_workspace_leapflow_config_probe(tmp_path) -> None:
+    result = await file_read({"path": str(tmp_path / ".leapflow" / "config.json")})
+
+    assert result["ok"] is False
+    assert result["error_type"] == "unsupported_config_probe"
+    assert result["retryable"] is False
+    assert result["config_locations"] == ["~/.leapflow/.env", "./.env"]
+    assert ".leapflow/config.json" in result["error"]
+
+
 def test_context_governance_controller_keeps_long_task_alias() -> None:
     controller = ContextGovernanceController(
         evidence_builder=ToolEvidenceBuilder(max_content_chars=240),
@@ -236,3 +274,223 @@ async def test_file_read_supports_range_outline_symbols_and_bounded_content(tmp_
     assert "def helper" in symbols["content"]
     assert bounded["truncated"] is True
     assert len(bounded["content"]) <= 220
+
+
+# ── CJK-aware token estimator ────────────────────────────────────────
+
+
+def test_estimate_text_tokens_cjk_counts_characters_as_tokens() -> None:
+    assert estimate_text_tokens("你好世界") == 4
+    assert estimate_text_tokens("hello") >= 1
+    mixed = "Hello 世界 test"
+    tokens = estimate_text_tokens(mixed)
+    assert tokens >= 2  # at least the 2 CJK characters
+    assert estimate_text_tokens("") == 0
+
+
+def test_estimate_text_tokens_latin_divides_by_four() -> None:
+    text = "a" * 400
+    tokens = estimate_text_tokens(text)
+    assert tokens == 100
+
+
+# ── Adaptive trim threshold scaling ──────────────────────────────────
+
+
+def test_adaptive_trim_chars_scales_with_context_length() -> None:
+    assert adaptive_trim_chars(2000, 0) == 2000
+    threshold_128k = adaptive_trim_chars(2000, 128_000)
+    threshold_256k = adaptive_trim_chars(2000, 256_000)
+    threshold_1m = adaptive_trim_chars(2000, 1_000_000)
+
+    assert threshold_128k > 2000
+    assert threshold_256k > threshold_128k
+    assert threshold_1m >= threshold_256k
+    assert threshold_1m <= 50_000  # ceiling
+
+
+def test_adaptive_trim_chars_never_below_base() -> None:
+    assert adaptive_trim_chars(5000, 32_000) >= 5000
+
+
+# ── CompressorConfig adaptive scaling ────────────────────────────────
+
+
+def test_compressor_config_applies_adaptive_scaling_from_context_length() -> None:
+    config = CompressorConfig(
+        context_length=256_000,
+        max_output_chars=2000,
+    )
+    assert config.trim_threshold_chars > 2000
+
+
+def test_compressor_config_respects_higher_explicit_threshold() -> None:
+    config = CompressorConfig(
+        context_length=128_000,
+        max_output_chars=30_000,
+    )
+    assert config.trim_threshold_chars >= 30_000
+
+
+# ── Budget-aware TrimStage ───────────────────────────────────────────
+
+
+def test_trim_stage_skips_when_budget_is_plentiful() -> None:
+    config = CompressorConfig(
+        token_budget=256_000,
+        context_length=256_000,
+        max_output_chars=2000,
+        enabled_stages=["trim"],
+    )
+    compressor = ContextCompressor(config)
+
+    messages = [
+        {"role": "system", "content": "system prompt"},
+        {"role": "tool", "content": "A" * 5_000},
+    ]
+    result = compressor.compress(messages, token_count=2_000)
+
+    assert result[1]["content"] == messages[1]["content"]
+    assert compressor.last_trace.stages_applied == []
+
+
+def test_trim_stage_activates_when_budget_pressure_exists() -> None:
+    config = CompressorConfig(
+        token_budget=10_000,
+        context_length=10_000,
+        max_output_chars=2000,
+        enabled_stages=["trim"],
+    )
+    compressor = ContextCompressor(config)
+
+    messages = [
+        {"role": "system", "content": "system"},
+        {"role": "tool", "content": "B" * 5_000},
+    ]
+    result = compressor.compress(messages, token_count=8_000)
+
+    assert result[1]["content"] != messages[1]["content"]
+    assert "trim" in compressor.last_trace.stages_applied
+
+
+def test_trim_stage_always_trims_ceiling_exceeding_messages() -> None:
+    config = CompressorConfig(
+        token_budget=1_000_000,
+        context_length=1_000_000,
+        max_output_chars=2000,
+        trim_ceiling_chars=10_000,
+        enabled_stages=["trim"],
+    )
+    compressor = ContextCompressor(config)
+
+    messages = [
+        {"role": "system", "content": "system"},
+        {"role": "tool", "content": "C" * 20_000},
+    ]
+    result = compressor.compress(messages, token_count=100)
+
+    assert result[1]["content"] != messages[1]["content"]
+    assert "trim" in compressor.last_trace.stages_applied
+
+
+# ── Compressor reconfigure ───────────────────────────────────────────
+
+
+def test_compressor_reconfigure_updates_budget_and_threshold() -> None:
+    compressor = ContextCompressor(CompressorConfig(
+        token_budget=128_000,
+        context_length=128_000,
+    ))
+    old_threshold = compressor._config.trim_threshold_chars
+
+    compressor.reconfigure(token_budget=256_000, context_length=256_000)
+
+    assert compressor._config.token_budget == 256_000
+    assert compressor._config.context_length == 256_000
+    assert compressor._config.trim_threshold_chars > old_threshold
+
+
+def test_compressor_reconfigure_preserves_summarize_state() -> None:
+    from leapflow.engine.context_compressor import SummarizeStage
+
+    compressor = ContextCompressor(CompressorConfig(
+        token_budget=128_000,
+        context_length=128_000,
+    ))
+
+    summarize_stages = [s for s in compressor._stages if s.name == "summarize"]
+    assert len(summarize_stages) == 1
+    stage = summarize_stages[0]
+    assert isinstance(stage, SummarizeStage)
+
+    stage._previous_summary = "test summary from earlier"
+    stage._compression_count = 3
+
+    compressor.reconfigure(token_budget=256_000, context_length=256_000)
+
+    summarize_after = [s for s in compressor._stages if s.name == "summarize"]
+    assert len(summarize_after) == 1
+    preserved = summarize_after[0]
+    assert preserved is stage
+    assert preserved._previous_summary == "test summary from earlier"
+    assert preserved._compression_count == 3
+
+
+# ── Deterministic summary preserves key info ─────────────────────────
+
+
+def test_deterministic_summary_preserves_tool_args_and_results() -> None:
+    from leapflow.engine.context_compressor import SummarizeStage
+
+    middle = [
+        {
+            "role": "assistant",
+            "content": "",
+            "tool_calls": [{
+                "function": {
+                    "name": "file_read",
+                    "arguments": '{"path": "/src/main.py"}',
+                },
+            }],
+        },
+        {
+            "role": "tool",
+            "content": '{"ok": true, "path": "/src/main.py", "exit_code": 0}',
+        },
+        {"role": "user", "content": "Please fix the bug in the database module"},
+    ]
+
+    summary = SummarizeStage._deterministic_summary(middle)
+
+    assert "file_read" in summary
+    assert "path=/src/main.py" in summary
+    assert "ok=True" in summary or "ok=true" in summary.lower()
+    assert "fix the bug in the database module" in summary
+
+
+# ── ToolEvidenceBuilder context-adaptive ─────────────────────────────
+
+
+def test_evidence_builder_adapts_to_context_length() -> None:
+    small = ToolEvidenceBuilder(max_content_chars=1200, context_length=0)
+    large = ToolEvidenceBuilder(max_content_chars=1200, context_length=256_000)
+
+    assert large._max_content_chars > small._max_content_chars
+
+
+def test_evidence_builder_ceiling() -> None:
+    huge = ToolEvidenceBuilder(max_content_chars=1200, context_length=2_000_000)
+    assert huge._max_content_chars <= 8_000
+
+
+# ── CJK-aware _estimate_tokens in compressor ─────────────────────────
+
+
+def test_compressor_estimate_tokens_is_cjk_aware() -> None:
+    messages_cjk = [{"role": "user", "content": "你" * 100}]
+    messages_latin = [{"role": "user", "content": "a" * 100}]
+
+    tokens_cjk = ContextCompressor._estimate_tokens(messages_cjk)
+    tokens_latin = ContextCompressor._estimate_tokens(messages_latin)
+
+    assert tokens_cjk > tokens_latin
diff --git a/tests/test_daemon_rpc.py b/tests/test_daemon_rpc.py
index ca0c5e0..a3b0a5f 100644
--- a/tests/test_daemon_rpc.py
+++ b/tests/test_daemon_rpc.py
@@ -379,6 +379,14 @@ async def model_info(self, model_name: str = "") -> dict[str, Any]:
                 "env_var": "LEAPFLOW_LLM_MODEL",
             }
 
+        async def app_command(self, args: str = "") -> dict[str, Any]:
+            return {
+                "ok": True,
+                "view": "list",
+                "args": args,
+                "result": {"platforms": [{"id": "feishu", "name": "Feishu", "state": "available"}]},
+            }
+
     with tempfile.TemporaryDirectory(prefix="lfd-", dir="/tmp") as root:
         server, task, run_dir = await _start_server(Path(root) / "run", service=SlashMetadataService())
         client = DaemonClient(run_dir / "leapd.sock")
@@ -386,6 +394,7 @@ async def model_info(self, model_name: str = "") -> dict[str, Any]:
             tools = await client.tools_list()
             usage = await client.usage_summary()
             model = await client.model_info("next-model")
+            app_payload = await client.app_command("list")
         finally:
             task.cancel()
             await server.stop()
@@ -397,6 +406,8 @@ async def model_info(self, model_name: str = "") -> dict[str, Any]:
     assert tools["groups"] == {"core": ["chat"]}
     assert usage["total_tokens"] == 15
     assert model["requested_model"] == "next-model"
+    assert app_payload["view"] == "list"
+    assert app_payload["args"] == "list"
 
 
 @pytest.mark.asyncio
@@ -438,11 +449,21 @@ def __init__(self, settings) -> None:
 
     with tempfile.TemporaryDirectory(prefix="lfd-", dir="/tmp") as root:
         settings = make_settings(root)
+        from leapflow.gateway.server import GatewayServer
+
+        gateway_server = GatewayServer(settings.profile_dir)
+        gateway_server.discover_manifests()
         service = RuntimeLeapService(settings, mock_host=True)
         service._ctx = FakeContext(settings)
-        tools = await service.tools_list()
-        usage = await service.usage_summary()
-        model = await service.model_info("other-model")
+        service._ctx.gateway_server = gateway_server
+        try:
+            tools = await service.tools_list()
+            usage = await service.usage_summary()
+            model = await service.model_info("other-model")
+            app_list = await service.app_command("list")
+            app_status = await service.app_command("status feishu")
+        finally:
+            await gateway_server.stop()
 
     assert tools["ok"] is True
     assert tools["total"] > 0
@@ -450,6 +471,12 @@ def __init__(self, settings) -> None:
     assert usage["context_length"] == 4096
     assert model["model"] == settings.llm_model
     assert model["requested_model"] == "other-model"
+    assert app_list["ok"] is True
+    assert app_list["view"] == "list"
+    assert {entry["id"] for entry in app_list["result"]["platforms"]} >= {"feishu", "telegram", "dingtalk"}
+    assert app_status["ok"] is True
+    assert app_status["view"] == "status"
+    assert app_status["result"]["platform"] == "feishu"
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_execution_backends.py b/tests/test_execution_backends.py
new file mode 100644
index 0000000..d6951b1
--- /dev/null
+++ b/tests/test_execution_backends.py
@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Mapping
+
+import pytest
+
+from leapflow.gateway.adapters.common import JsonBody
+from leapflow.gateway.backends.cli_backend import CliBackend
+from leapflow.gateway.backends.rest_backend import RestBackend
+from leapflow.gateway.connectors.protocol import ActionSpec, BackendKind
+
+
+class FakeProcess:
+    def __init__(self, returncode: int, stdout: bytes, stderr: bytes = b"") -> None:
+        self.returncode = returncode
+        self._stdout = stdout
+        self._stderr = stderr
+
+    async def communicate(self) -> tuple[bytes, bytes]:
+        return self._stdout, self._stderr
+
+
+class HangingFakeProcess:
+    def __init__(self) -> None:
+        self.returncode = None
+        self.killed = False
+        self.waited = False
+
+    async def communicate(self) -> tuple[bytes, bytes]:
+        await asyncio.sleep(60)
+        return b"", b""
+
+    def kill(self) -> None:
+        self.killed = True
+        self.returncode = -9
+
+    async def wait(self) -> int:
+        self.waited = True
+        return int(self.returncode or 0)
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_executes_registered_action(monkeypatch) -> None:
+    captured: list[tuple[str, ...]] = []
+
+    async def fake_exec(*argv, **_kwargs):
+        captured.append(tuple(str(arg) for arg in argv))
+        return FakeProcess(0, b'{"ok": true, "data": {"message_id": "om_1"}}')
+
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="lark-cli", profile="bot-reader", identity="bot")
+    spec = ActionSpec(
+        name="im.send_message",
+        backend_kind=BackendKind.CLI.value,
+        backend_config={"argv": ("im", "+messages-send", "--chat-id", "{chat_id}", "--text", "{text}")},
+    )
+
+    result = await backend.execute(spec, {"chat_id": "oc_1", "text": "hello"})
+
+    assert result.ok is True
+    assert result.resource_id == "om_1"
+    assert captured[0] == (
+        "lark-cli",
+        "--profile",
+        "bot-reader",
+        "--as",
+        "bot",
+        "im",
+        "+messages-send",
+        "--chat-id",
+        "oc_1",
+        "--text",
+        "hello",
+    )
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_normalizes_error(monkeypatch) -> None:
+    async def fake_exec(*_argv, **_kwargs):
+        return FakeProcess(1, b"", b'{"ok": false, "error": {"message": "missing scope"}}')
+
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="lark-cli")
+    spec = ActionSpec(
+        name="im.send_message",
+        backend_kind=BackendKind.CLI.value,
+        backend_config={"argv": ("im", "+messages-send")},
+    )
+
+    result = await backend.execute(spec, {})
+
+    assert result.ok is False
+    assert result.error == "missing scope"
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_preview_uses_dry_run_template_without_execution() -> None:
+    backend = CliBackend(binary="lark-cli", profile="bot-reader", identity="bot")
+    spec = ActionSpec(
+        name="docs.create_markdown",
+        backend_kind=BackendKind.CLI.value,
+        backend_config={
+            "argv": ("docs", "+create", "--title", "{title}"),
+            "dry_run_argv": ("docs", "+create", "--title", "{title}", "--dry-run"),
+            "approval_summary": "Create Feishu document {title} as {identity} using profile {profile}.",
+        },
+    )
+
+    preview = await backend.preview(spec, {"title": "Demo"})
+
+    assert preview.ok is True
+    assert preview.data["dry_run"] is True
+    assert preview.data["argv"] == [
+        "lark-cli", "--profile", "bot-reader", "--as", "bot",
+        "docs", "+create", "--title", "Demo", "--dry-run",
+    ]
+    assert preview.summary == "Create Feishu document Demo as bot using profile bot-reader."
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_status_reports_missing_binary_recovery(monkeypatch) -> None:
+    monkeypatch.setattr("shutil.which", lambda _binary: None)
+    backend = CliBackend(binary="missing-lark-cli", profile="work", identity="bot")
+
+    status = await backend.status()
+
+    assert status.ok is False
+    assert status.metadata["recoverable"] is True
+    assert status.metadata["binary"] == "missing-lark-cli"
+    assert status.metadata["profile"] == "work"
+    assert "Install 'missing-lark-cli'" in status.metadata["recovery_hint"]
+    assert status.metadata["next_steps"]
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_status_reports_auth_recovery(monkeypatch) -> None:
+    async def fake_exec(*_argv, **_kwargs):
+        return FakeProcess(1, b"", b'{"ok": false, "error": {"message": "missing scope im:message"}}')
+
+    monkeypatch.setattr("shutil.which", lambda _binary: "/usr/local/bin/lark-cli")
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="lark-cli", profile="work")
+
+    status = await backend.status()
+
+    assert status.ok is False
+    assert status.metadata["binary_path"] == "/usr/local/bin/lark-cli"
+    assert status.metadata["auth_status"] == "not_ready"
+    assert "permission scopes" in status.metadata["recovery_hint"]
+    assert "lark-cli --profile work auth login --json" in status.metadata["next_steps"]
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_appends_explicit_output_args(monkeypatch) -> None:
+    captured: list[tuple[str, ...]] = []
+
+    async def fake_exec(*argv, **_kwargs):
+        captured.append(tuple(str(arg) for arg in argv))
+        return FakeProcess(0, b'{"ok": true, "data": {"id": "item-1"}}')
+
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="demo-cli")
+    spec = ActionSpec(
+        name="repo.read_file",
+        backend_kind=BackendKind.CLI.value,
+        backend_config={"argv": ("repo", "read"), "output_args": ("--format", "json")},
+    )
+
+    result = await backend.execute(spec, {})
+
+    assert result.ok is True
+    assert captured[0] == ("demo-cli", "repo", "read", "--format", "json")
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_status_reports_contract_mismatch(monkeypatch) -> None:
+    async def fake_exec(*_argv, **_kwargs):
+        return FakeProcess(1, b"", b'unknown flag: --format')
+
+    monkeypatch.setattr("shutil.which", lambda _binary: "/usr/local/bin/lark-cli")
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="lark-cli", profile="work")
+
+    status = await backend.status()
+
+    assert status.ok is False
+    assert status.metadata["failure_code"] == "cli_contract_mismatch"
+    assert status.metadata["recoverable"] is False
+    assert "lark-cli --profile work auth status --json" in status.metadata["next_steps"]
+
+
+@pytest.mark.asyncio
+async def test_cli_backend_kills_subprocess_on_timeout(monkeypatch) -> None:
+    process = HangingFakeProcess()
+
+    async def fake_exec(*_argv, **_kwargs):
+        return process
+
+    monkeypatch.setattr("asyncio.create_subprocess_exec", fake_exec)
+    backend = CliBackend(binary="lark-cli")
+    spec = ActionSpec(
+        name="im.send_message",
+        backend_kind=BackendKind.CLI.value,
+        backend_config={"argv": ("im", "+messages-send"), "timeout_s": 0.01},
+    )
+
+    result = await backend.execute(spec, {})
+
+    assert result.ok is False
+    assert "timed out" in result.error
+    assert process.killed is True
+    assert process.waited is True
+
+
+@pytest.mark.asyncio
+async def test_rest_backend_preview_is_side_effect_free() -> None:
+    backend = RestBackend(base_url="https://api.example.test", token="token")
+    spec = ActionSpec(
+        name="repo.read_file",
+        backend_kind=BackendKind.REST.value,
+        backend_config={"method": "GET", "path": "/repos/{repo}/contents/{path}"},
+    )
+
+    preview = await backend.preview(spec, {"repo": "demo", "path": "README.md"})
+
+    assert preview.ok is True
+    assert preview.summary == "GET /repos/demo/contents/README.md"
+    assert preview.data["backend_kind"] == "rest"
+
+
+class FakeHttpClient:
+    def __init__(self) -> None:
+        self.requests: list[dict[str, Any]] = []
+
+    async def request_json(
+        self,
+        method: str,
+        url: str,
+        *,
+        json_body: Mapping[str, Any] | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout_s: float = 10.0,
+    ) -> tuple[int, JsonBody]:
+        self.requests.append({
+            "method": method,
+            "url": url,
+            "json_body": dict(json_body or {}),
+            "headers": dict(headers or {}),
+            "timeout_s": timeout_s,
+        })
+        return 200, {"id": "repo-1"}
+
+
+@pytest.mark.asyncio
+async def test_rest_backend_executes_registered_action() -> None:
+    http = FakeHttpClient()
+    backend = RestBackend(base_url="https://api.example.test", token="token", http_client=http)
+    spec = ActionSpec(
+        name="repo.read_file",
+        backend_kind=BackendKind.REST.value,
+        backend_config={"method": "POST", "path": "/repos/{repo}/contents", "json_body": {"path": "{path}"}},
+    )
+
+    result = await backend.execute(spec, {"repo": "demo", "path": "README.md"})
+
+    assert result.ok is True
+    assert result.resource_id == "repo-1"
+    assert http.requests[0]["url"] == "https://api.example.test/repos/demo/contents"
+    assert http.requests[0]["json_body"] == {"path": "README.md"}
+    assert http.requests[0]["headers"]["Authorization"] == "Bearer token"
diff --git a/tests/test_gateway_adapters.py b/tests/test_gateway_adapters.py
index 9acfe56..6fab544 100644
--- a/tests/test_gateway_adapters.py
+++ b/tests/test_gateway_adapters.py
@@ -10,6 +10,7 @@
 from leapflow.gateway.adapters.feishu import FeishuAdapter
 from leapflow.gateway.adapters.telegram import TelegramAdapter
 from leapflow.gateway.adapters.webhook import WebhookAdapter
+from leapflow.gateway.connectors.protocol import ActionResult, BackendStatus
 from leapflow.gateway.manifest import ManifestLoader
 from leapflow.gateway.protocol import InboundMessage, OutboundContent, SendTarget
 from leapflow.gateway.server import GatewayServer
@@ -48,7 +49,7 @@ def test_builtin_manifest_adapter_modules_are_importable() -> None:
         "api_server": {"api_key": "0123456789abcdef"},
         "webhook": {"webhook_secret": ""},
         "telegram": {"bot_token": "token"},
-        "feishu": {"app_id": "app", "app_secret": "secret"},
+        "feishu": {},
         "dingtalk": {"app_key": "key", "app_secret": "secret"},
     }
 
@@ -153,43 +154,40 @@ async def test_telegram_adapter_send_and_update_normalization() -> None:
     assert received[0].text == "incoming"
 
 
+class FakeExecutionBackend:
+    kind = "cli"
+
+    def __init__(self) -> None:
+        self.executed: list[tuple[str, Mapping[str, Any]]] = []
+
+    async def status(self) -> BackendStatus:
+        return BackendStatus(ok=True, backend_kind=self.kind)
+
+    async def authenticate(self, payload: Mapping[str, Any]) -> BackendStatus:
+        return BackendStatus(ok=True, backend_kind=self.kind, metadata=dict(payload))
+
+    async def execute(self, spec, payload: Mapping[str, Any]) -> ActionResult:
+        self.executed.append((spec.name, payload))
+        return ActionResult(ok=True, resource_id="om_1", data={"message_id": "om_1"})
+
+
 @pytest.mark.asyncio
-async def test_feishu_adapter_connect_send_and_event_normalization() -> None:
-    fake_http = FakeJsonHttpClient({
-        "tenant_access_token": (200, {"code": 0, "tenant_access_token": "tenant-token"}),
-        "/im/v1/messages": (200, {"code": 0, "data": {"message_id": "om_1"}}),
-    })
-    received: list[InboundMessage] = []
-    adapter = FeishuAdapter(app_id="app", app_secret="secret", port=0, http_client=fake_http)
-    adapter.on_message = received.append
+async def test_feishu_adapter_uses_cli_backend_for_send() -> None:
+    backend = FakeExecutionBackend()
+    adapter = FeishuAdapter(profile="bot-reader", backend=backend)
 
     await adapter.connect()
-    try:
-        result = await adapter.send(
-            SendTarget(platform="feishu", chat_id="oc_1"),
-            OutboundContent(text="hello feishu"),
-        )
-        status, data = await post_json_for_test(adapter.local_url, {
-            "event": {
-                "message": {
-                    "message_id": "om_in",
-                    "chat_id": "oc_1",
-                    "chat_type": "group",
-                    "content": "{\"text\": \"incoming feishu\"}",
-                },
-                "sender": {"sender_id": {"open_id": "ou_1"}, "sender_type": "user"},
-            },
-        })
-    finally:
-        await adapter.disconnect()
+    result = await adapter.send(
+        SendTarget(platform="feishu", chat_id="oc_1"),
+        OutboundContent(text="hello feishu"),
+    )
+    await adapter.disconnect()
 
     assert result.ok is True
-    assert status == 202
-    assert data["ok"] is True
     assert result.message_id == "om_1"
-    assert fake_http.requests[1]["headers"]["Authorization"] == "Bearer tenant-token"
-    assert received[0].text == "incoming feishu"
-    assert received[0].source.user_id == "ou_1"
+    assert backend.executed == [
+        ("im.send_message", {"chat_id": "oc_1", "thread_id": "", "text": "hello feishu"}),
+    ]
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_gateway_tool_e2e.py b/tests/test_gateway_tool_e2e.py
index 7456294..8f32418 100644
--- a/tests/test_gateway_tool_e2e.py
+++ b/tests/test_gateway_tool_e2e.py
@@ -1,17 +1,68 @@
 from __future__ import annotations
 
+from types import SimpleNamespace
+
 import pytest
 
+from leapflow.gateway.connectors.protocol import ActionPreview, ActionResult, ActionSpec, BackendKind
 from leapflow.gateway.protocol import OutboundContent, SendResult, SendTarget
 from leapflow.gateway.server import GatewayServer
 from leapflow.tools.gateway_tool import (
+    build_app_connector_prompt_section,
     gateway_connect_handler,
     gateway_send_handler,
+    platform_action_handler,
+    platform_connect_handler,
     set_gateway_approval_gate,
     set_gateway_server,
 )
 
 
+@pytest.mark.asyncio
+async def test_app_slash_payloads_reuse_platform_connect_and_manifests(tmp_path) -> None:
+    from leapflow.cli.commands.slash_handlers import build_app_payload
+
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    ctx = SimpleNamespace(gateway_server=server)
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        listed = await build_app_payload(ctx, "")
+        guide = await build_app_payload(ctx, "FeiShu")
+        status = await build_app_payload(ctx, "status feishu")
+        actions = await build_app_payload(ctx, "actions feishu")
+        telegram_connect = await build_app_payload(ctx, "connect telegram")
+        invalid_option = await build_app_payload(ctx, "connect feishu --unknown value")
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert listed["ok"] is True
+    assert listed["view"] == "list"
+    assert {entry["id"] for entry in listed["result"]["platforms"]} >= {"feishu", "telegram", "dingtalk"}
+    assert guide["ok"] is True
+    assert guide["view"] == "guide"
+    assert guide["result"]["platform"] == "飞书 (Feishu/Lark)"
+    assert guide["result"]["setup_form"]["backend"]["kind"] == "cli"
+    assert status["ok"] is True
+    assert status["result"]["platform"] == "feishu"
+    assert actions["ok"] is True
+    assert set(actions["actions"]) == {
+        "im.send_message", "im.list_chats", "im.search_chats",
+        "docs.create_markdown", "calendar.create_event",
+        "drive.search", "sheets.append_row", "mail.search_unread", "task.create",
+    }
+    assert telegram_connect["ok"] is True
+    assert telegram_connect["view"] == "guide"
+    assert telegram_connect["result"]["required_fields"][0]["key"] == "bot_token"
+    assert invalid_option["ok"] is False
+    assert "Unknown option" in invalid_option["error"]
+    assert "feishu" in invalid_option["available"]
+
+
 @pytest.mark.asyncio
 async def test_gateway_connect_tool_can_connect_builtin_webhook(tmp_path) -> None:
     server = GatewayServer(tmp_path)
@@ -54,6 +105,17 @@ class FakeSendAdapter:
 
     def __init__(self) -> None:
         self.sent: list[tuple[SendTarget, OutboundContent]] = []
+        self.spec = ActionSpec(
+            name="im.send_message",
+            backend_kind=BackendKind.CLI.value,
+            effect="send",
+            schema={
+                "type": "object",
+                "required": ["chat_id", "text"],
+                "properties": {"chat_id": {"type": "string"}, "text": {"type": "string"}},
+            },
+            risk_level="high",
+        )
 
     async def connect(self, *, is_reconnect: bool = False) -> None:
         pass
@@ -65,6 +127,28 @@ async def send(self, target: SendTarget, content: OutboundContent) -> SendResult
         self.sent.append((target, content))
         return SendResult(ok=True, message_id="fake-1")
 
+    def action_spec(self, action: str) -> ActionSpec | None:
+        return self.spec if action == self.spec.name else None
+
+    def action_specs(self) -> dict[str, ActionSpec]:
+        return {self.spec.name: self.spec}
+
+    async def preview_action(self, action: str, payload: dict) -> ActionPreview:
+        if action != self.spec.name:
+            return ActionPreview(ok=False, error="unknown action")
+        return ActionPreview(ok=True, summary=f"preview {action}")
+
+    async def execute_action(self, action: str, payload: dict) -> ActionResult:
+        self.sent.append((
+            SendTarget(
+                platform="fake",
+                chat_id=str(payload.get("chat_id", "")),
+                thread_id=str(payload.get("thread_id", "")),
+            ),
+            OutboundContent(text=str(payload.get("text", ""))),
+        ))
+        return ActionResult(ok=True, resource_id="fake-action-1")
+
 
 class DenyGate:
     async def evaluate(self, action):
@@ -94,7 +178,10 @@ async def test_gateway_send_tool_dispatches_to_connected_adapter(tmp_path) -> No
         set_gateway_approval_gate(None)
         set_gateway_server(None)
 
-    assert result == {"ok": True, "message_id": "fake-1"}
+    assert result["ok"] is True
+    assert result["resource_id"] == "fake-action-1"
+    assert result["message_id"] == "fake-action-1"
+    assert result["source_tool"] == "gateway_send"
     target, content = adapter.sent[0]
     assert target.chat_id == "chat-1"
     assert target.thread_id == "thread-1"
@@ -121,3 +208,446 @@ async def test_gateway_send_tool_honors_approval_denial(tmp_path) -> None:
 
     assert result == {"ok": False, "error": "denied for test"}
     assert adapter.sent == []
+
+
+@pytest.mark.asyncio
+async def test_gateway_send_returns_onboarding_hint_when_registered_action_is_not_connected(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        result = await gateway_send_handler({
+            "platform": "feishu",
+            "chat_id": "oc_1",
+            "text": "hello",
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert result["failure_code"] == "platform_not_connected"
+    assert "registered action 'im.send_message'" in result["error"]
+    assert "platform_connect action=preflight platform=feishu" in result["next_steps"]
+
+
+@pytest.mark.asyncio
+async def test_platform_action_distinguishes_registered_but_not_connected_action(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        result = await platform_action_handler({
+            "platform": "feishu",
+            "action": "im.send_message",
+            "payload": {"chat_id": "oc_1", "text": "hello"},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert result["failure_code"] == "platform_not_connected"
+    assert result["recovery_hint"]
+    assert "platform_connect action=connect platform=feishu" in result["next_steps"]
+
+
+@pytest.mark.asyncio
+async def test_platform_action_reports_unknown_action_with_expanded_registry(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        # im.fake_invented is NOT in the YAML registry
+        result = await platform_action_handler({
+            "platform": "feishu",
+            "action": "im.fake_invented",
+            "payload": {},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert result["failure_code"] == "unknown_platform_action"
+    assert result["retryable"] is True
+    # All 9 registered actions should be in available_action_names
+    assert "im.send_message" in result["available_action_names"]
+    assert "im.list_chats" in result["available_action_names"]
+    assert "im.search_chats" in result["available_action_names"]
+    assert any(item["name"] == "im.send_message" for item in result["available_actions"])
+
+
+@pytest.mark.asyncio
+async def test_platform_action_list_chats_and_search_chats_are_registered(tmp_path) -> None:
+    """im.list_chats and im.search_chats are now registered discovery actions."""
+    from leapflow.gateway.action_packs.feishu import ACTION_SPECS
+
+    assert "im.list_chats" in ACTION_SPECS
+    assert "im.search_chats" in ACTION_SPECS
+    assert ACTION_SPECS["im.list_chats"].effect == "read"
+    assert ACTION_SPECS["im.search_chats"].effect == "read"
+    assert ACTION_SPECS["im.search_chats"].schema.get("required") == ["query"]
+
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        # These should be platform_not_connected (registered but not connected)
+        # rather than unknown_platform_action
+        result_list = await platform_action_handler({
+            "platform": "feishu",
+            "action": "im.list_chats",
+            "payload": {},
+        })
+        result_search = await platform_action_handler({
+            "platform": "feishu",
+            "action": "im.search_chats",
+            "payload": {"query": "LeapFlow"},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result_list["failure_code"] == "platform_not_connected"
+    assert result_search["failure_code"] == "platform_not_connected"
+
+
+@pytest.mark.asyncio
+async def test_platform_action_reports_wrong_namespace_for_management_action(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        result = await platform_action_handler({
+            "platform": "feishu",
+            "action": "list",
+            "payload": {},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert result["failure_code"] == "wrong_action_namespace"
+    assert result["correct_tool"] == "platform_connect"
+    assert result["retryable"] is True
+    assert "list" in result["available_management_actions"]
+
+
+@pytest.mark.asyncio
+async def test_platform_action_reports_unknown_platform_with_available_list(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        result = await platform_action_handler({
+            "platform": "gateway",
+            "action": "list_actions",
+            "payload": {"platform": "feishu"},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert result["failure_code"] == "unknown_platform"
+    assert result["retryable"] is True
+    assert "feishu" in result["available_platforms"]
+
+
+class CaptureGate:
+    def __init__(self) -> None:
+        self.actions = []
+
+    async def evaluate(self, action):
+        self.actions.append(action)
+
+        class Result:
+            approved = True
+            denial_message = ""
+
+        return Result()
+
+
+@pytest.mark.asyncio
+async def test_platform_action_uses_registered_spec_for_approval_and_summary(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    adapter = FakeSendAdapter()
+    gate = CaptureGate()
+    server._adapters["fake"] = adapter
+    set_gateway_server(server)
+    set_gateway_approval_gate(gate)
+
+    try:
+        result = await platform_action_handler({
+            "platform": "fake",
+            "action": "im.send_message",
+            "payload": {"chat_id": "chat-1", "text": "hello"},
+        })
+    finally:
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is True
+    assert result["platform"] == "fake"
+    assert result["action"] == "im.send_message"
+    assert result["output_policy"] == "summary"
+    assert gate.actions[0].effect == "send"
+    assert gate.actions[0].metadata["backend_kind"] == "cli"
+    assert gate.actions[0].metadata["risk_level"] == "high"
+
+
+@pytest.mark.asyncio
+async def test_platform_events_report_unavailable_for_feishu(tmp_path) -> None:
+    from leapflow.gateway.adapters.feishu import FeishuAdapter
+    from leapflow.gateway.connectors.protocol import BackendStatus
+
+    class ReadyBackend:
+        kind = "cli"
+
+        async def status(self) -> BackendStatus:
+            return BackendStatus(ok=True, backend_kind=self.kind)
+
+        async def authenticate(self, payload):
+            return BackendStatus(ok=True, backend_kind=self.kind)
+
+        async def execute(self, spec, payload):
+            return ActionResult(ok=True)
+
+    server = GatewayServer(tmp_path)
+    adapter = FeishuAdapter(backend=ReadyBackend())
+    server._adapters["feishu"] = adapter
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        status = await platform_connect_handler({"action": "events_status", "platform": "feishu"})
+        started = await platform_connect_handler({"action": "events_start", "platform": "feishu"})
+    finally:
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert status["ok"] is False
+    assert started["ok"] is False
+    assert status["metadata"]["available"] is False
+    assert status["metadata"]["configuration_hint"]
+    assert "inbound events are not enabled" in status["detail"]
+
+
+@pytest.mark.asyncio
+async def test_platform_connect_can_configure_credentialless_platform(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        guide = await platform_connect_handler({"action": "guide", "platform": "feishu"})
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert guide["ok"] is True
+    assert guide["required_fields"] == []
+    assert guide["setup_form"]["backend"]["kind"] == "cli"
+    assert guide["setup_form"]["actions"]["pack"] == "leapflow.gateway.action_packs.feishu"
+    assert guide["preflight_checks"][0]["command"] == "lark-cli --version"
+    assert guide["preflight_checks"][0]["kind"] == "check"
+    assert guide["preflight_checks"][1]["command"] == "lark-cli auth login --json"
+    assert guide["preflight_checks"][1]["kind"] == "interactive_auth"
+    assert guide["preflight_checks"][2]["command"] == "lark-cli auth status --json"
+    assert guide["preflight_result"]["backend_kind"] == "cli"
+    assert guide["onboarding_state"]["platform_id"] == "feishu"
+    assert guide["recovery_hint"]
+    assert "lark-cli" in guide["setup_guide"]
+
+
+@pytest.mark.asyncio
+async def test_platform_connect_records_pending_onboarding_state_for_cli_preflight(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        guide = await platform_connect_handler({
+            "action": "guide",
+            "platform": "feishu",
+            "options": {"binary": "definitely-missing-cli-for-onboarding-test"},
+        })
+        section = build_app_connector_prompt_section()
+        preflight = await platform_connect_handler({
+            "action": "preflight",
+            "platform": "feishu",
+            "options": {"binary": "definitely-missing-cli-for-onboarding-test"},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert guide["ok"] is True
+    assert guide["preflight_result"]["ready"] is False
+    assert guide["onboarding_state"]["stage"] == "cli_missing"
+    assert guide["preflight_result"]["checks"][0]["status"] == "failed"
+    assert guide["preflight_result"]["checks"][1]["status"] == "blocked"
+    assert "Pending App Onboarding State" in section
+    assert "platform=`feishu`" in section
+    assert preflight["ok"] is False
+    assert preflight["onboarding_state"]["stage"] == "cli_missing"
+
+
+@pytest.mark.asyncio
+async def test_app_connector_prompt_section_exposes_supported_apps_without_classifying_text(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        section = build_app_connector_prompt_section()
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert "App Connector Capability Index" in section
+    assert "`feishu`" in section
+    assert "`telegram`" in section
+    assert "`dingtalk`" in section
+    assert "platform_connect" in section
+    assert "SDK/Webhook sample code" in section
+    assert "im.send_message" in section
+    assert "management namespace" in section
+
+
+@pytest.mark.asyncio
+async def test_platform_connect_prompt_contract_still_uses_gateway_handler(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        guide = await platform_connect_handler({"action": "guide", "platform": "telegram"})
+        connect_without_secret = await platform_connect_handler({"action": "connect", "platform": "telegram"})
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert guide["ok"] is True
+    assert guide["platform"] == "Telegram"
+    assert guide["required_fields"][0]["key"] == "bot_token"
+    assert connect_without_secret["ok"] is True
+    assert connect_without_secret["setup_form"]["fields"][0]["type"] == "password"
+
+
+@pytest.mark.asyncio
+async def test_platform_connect_failure_returns_feishu_recovery_hint(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        result = await platform_connect_handler({
+            "action": "connect",
+            "platform": "feishu",
+            "options": {"binary": "definitely-missing-lark-cli-for-test"},
+        })
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result["ok"] is False
+    assert "Connection failed" in result["error"]
+    assert "Install 'definitely-missing-lark-cli-for-test'" in result["recovery_hint"]
+    assert result["next_steps"]
+    assert result["diagnostics"]["profile"] == "default"
+
+
+@pytest.mark.asyncio
+async def test_platform_status_exposes_feishu_connector_diagnostics(tmp_path) -> None:
+    from leapflow.gateway.adapters.feishu import FeishuAdapter
+    from leapflow.gateway.connectors.protocol import BackendStatus
+
+    class ReadyBackend:
+        kind = "cli"
+        binary = "lark-cli"
+        profile = "work"
+        identity = "bot"
+
+        async def status(self) -> BackendStatus:
+            return BackendStatus(ok=True, backend_kind=self.kind)
+
+        async def authenticate(self, payload):
+            return BackendStatus(ok=True, backend_kind=self.kind)
+
+        async def execute(self, spec, payload):
+            return ActionResult(ok=True)
+
+    server = GatewayServer(tmp_path)
+    server.discover_manifests()
+    server._adapters["feishu"] = FeishuAdapter(backend=ReadyBackend())
+    server._connected_since["feishu"] = 1.0
+    set_gateway_server(server)
+    set_gateway_approval_gate(None)
+
+    try:
+        status = await platform_connect_handler({"action": "status", "platform": "feishu"})
+        listed = await platform_connect_handler({"action": "list"})
+    finally:
+        await server.stop()
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert status["ok"] is True
+    assert status["diagnostics"]["backend_kind"] == "cli"
+    assert status["diagnostics"]["profile"] == "work"
+    assert status["diagnostics"]["event_source"]["mode"] == "outbound_actions_only"
+    feishu_entry = next(entry for entry in listed["platforms"] if entry["id"] == "feishu")
+    assert feishu_entry["diagnostics"]["identity"] == "bot"
+
+
+@pytest.mark.asyncio
+async def test_platform_action_honors_approval_denial(tmp_path) -> None:
+    server = GatewayServer(tmp_path)
+    adapter = FakeSendAdapter()
+    server._adapters["fake"] = adapter
+    set_gateway_server(server)
+    set_gateway_approval_gate(DenyGate())
+
+    try:
+        result = await platform_action_handler({
+            "platform": "fake",
+            "action": "im.send_message",
+            "payload": {"chat_id": "chat-1", "text": "blocked outbound"},
+        })
+    finally:
+        set_gateway_approval_gate(None)
+        set_gateway_server(None)
+
+    assert result == {"ok": False, "error": "denied for test"}
+    assert adapter.sent == []
diff --git a/tests/test_pure_algorithms.py b/tests/test_pure_algorithms.py
index b636ee8..dcfb0d1 100644
--- a/tests/test_pure_algorithms.py
+++ b/tests/test_pure_algorithms.py
@@ -138,6 +138,7 @@ def test_causal_graph_connected_components() -> None:
 def test_unified_system_template_escapes_literal_tool_protocol_json() -> None:
     rendered = UNIFIED_SYSTEM_TEMPLATE.format(
         tool_catalog="- **skills_list**(): List installed skills",
+        app_connector_section="",
         skill_section="",
         memory_context="",
     )
diff --git a/tests/test_slash_command_router.py b/tests/test_slash_command_router.py
index 2c39cca..1fccac9 100644
--- a/tests/test_slash_command_router.py
+++ b/tests/test_slash_command_router.py
@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from leapflow.cli.commands.router import CommandRouter
+from leapflow.cli.commands.interactive import _is_app_command
 
 
 def test_command_router_parses_command_args_and_runtime_support() -> None:
@@ -15,6 +16,64 @@ def test_command_router_parses_command_args_and_runtime_support() -> None:
     assert router.unsupported_result(invocation) is None
 
 
+def test_command_router_parses_app_subcommands_without_daemon_parity() -> None:
+    in_process_router = CommandRouter("in_process")
+    daemon_router = CommandRouter("daemon")
+
+    invocation = in_process_router.parse("/app status feishu")
+    daemon_invocation = daemon_router.parse("/app connect feishu")
+
+    assert invocation is not None
+    assert invocation.command.name == "app status"
+    assert invocation.args == "feishu"
+    assert in_process_router.unsupported_result(invocation) is None
+    assert daemon_invocation is not None
+    assert daemon_invocation.command.name == "app connect"
+    unsupported = daemon_router.unsupported_result(daemon_invocation)
+    assert unsupported is not None
+    assert "/app connect" in unsupported.title
+
+
+def test_app_commands_daemon_parity_boundary() -> None:
+    """Read-only /app commands are available in daemon; write commands are not."""
+    daemon_router = CommandRouter("daemon")
+
+    # Commands that MUST be supported in daemon mode
+    for cmd_text in ("/app", "/app list", "/app status feishu", "/app actions feishu"):
+        inv = daemon_router.parse(cmd_text)
+        assert inv is not None, f"parse failed for {cmd_text}"
+        assert daemon_router.unsupported_result(inv) is None, (
+            f"{cmd_text} should be supported in daemon mode"
+        )
+
+    # Commands that must NOT be supported in daemon mode
+    for cmd_text in ("/app connect feishu", "/app disconnect feishu", "/app remove feishu"):
+        inv = daemon_router.parse(cmd_text)
+        assert inv is not None, f"parse failed for {cmd_text}"
+        unsupported = daemon_router.unsupported_result(inv)
+        assert unsupported is not None, f"{cmd_text} should be blocked in daemon mode"
+        assert unsupported.ok is False
+
+
+def test_app_commands_are_registered_for_completion() -> None:
+    from leapflow.cli.commands.registry import completion_entries
+
+    entries = dict(completion_entries())
+
+    assert entries["app"] == "List supported external apps or open an app setup guide"
+    assert entries["app list"] == "List supported external apps"
+    assert entries["app status"] == "Show App Connector status"
+    assert entries["app connect"] == "Connect a supported external app"
+    assert entries["app actions"] == "List App Connector action domains"
+
+
+def test_interactive_app_command_boundary_rejects_prefix_collisions() -> None:
+    assert _is_app_command("app") is True
+    assert _is_app_command("app status feishu") is True
+    assert _is_app_command("apple") is False
+    assert _is_app_command("application status") is False
+
+
 def test_command_router_returns_standard_unsupported_result() -> None:
     router = CommandRouter("daemon")
 
diff --git a/tests/test_tui_command_queue.py b/tests/test_tui_command_queue.py
index 9cfa684..5952938 100644
--- a/tests/test_tui_command_queue.py
+++ b/tests/test_tui_command_queue.py
@@ -132,6 +132,57 @@ async def test_tui_approval_modal_preserves_frame_and_choices_in_small_height()
     assert "4. Deny" in rendered
 
 
+@pytest.mark.asyncio
+async def test_tui_approval_modal_constrained_height_preserves_choices() -> None:
+    request = ApprovalRequest(
+        category="shell.command",
+        detail="python3 -m pip install aiohttp requests --user --quiet 2>&1\n" * 10,
+        choices=("allow_once", "allow_session", "deny"),
+        display={
+            "summary": "Run a potentially dangerous shell command",
+            "reason": "This shell command has side effects or reaches external systems.",
+        },
+    )
+    modal = app_module.ApprovalModal.create(request)
+
+    unconstrained = modal.line_count()
+    constrained_limit = 12
+    assert unconstrained > constrained_limit
+
+    rendered = "".join(text for _style, text in modal.fragments(max_lines=constrained_limit))
+    lines = [line for line in rendered.splitlines() if line]
+
+    assert lines[0].startswith("╭") and lines[0].endswith("╮")
+    assert lines[-1].startswith("╰") and lines[-1].endswith("╯")
+    assert "1. Allow once" in rendered
+    assert "2. Allow for this session" in rendered
+    assert "3. Deny" in rendered
+    assert len(lines) <= constrained_limit
+
+    constrained_count = modal.line_count(max_lines=constrained_limit)
+    assert constrained_count <= constrained_limit
+    assert constrained_count == len(lines)
+
+
+@pytest.mark.asyncio
+async def test_tui_approval_modal_extremely_tight_height_still_shows_choices() -> None:
+    request = ApprovalRequest(
+        category="shell.command",
+        detail="rm -rf /important",
+        choices=("allow_once", "deny"),
+        display={"summary": "Run shell command", "reason": "Dangerous command"},
+    )
+    modal = app_module.ApprovalModal.create(request)
+
+    rendered = "".join(text for _style, text in modal.fragments(max_lines=7))
+    lines = [line for line in rendered.splitlines() if line]
+
+    assert lines[0].startswith("╭") and lines[0].endswith("╮")
+    assert lines[-1].startswith("╰") and lines[-1].endswith("╯")
+    assert "1. Allow once" in rendered
+    assert "2. Deny" in rendered
+
+
 @pytest.mark.asyncio
 async def test_tui_approval_modal_shortcuts_and_details() -> None:
     app, _console, _status = _make_app()
diff --git a/tests/test_tui_theme.py b/tests/test_tui_theme.py
index 88b4ed7..301f4bb 100644
--- a/tests/test_tui_theme.py
+++ b/tests/test_tui_theme.py
@@ -157,12 +157,15 @@ def test_leap_app_layout_keeps_status_breathing_gap(tmp_path) -> None:
     root = app._app.layout.container.content
     children = root.children
 
-    assert len(children) == 4
-    assert children[1].style == "class:status-gap"
-    assert children[1].height == 1
+    assert len(children) == 5
+    status_gap = children[2].content
+    status_bar = children[3]
+    input_area = children[4].content
+    assert status_gap.style == "class:status-gap"
+    assert status_gap.height == 1
     assert app._build_style().get_attrs_for_style_str("class:status-gap").bgcolor == ""
-    assert children[2].style == "class:status-bar"
-    assert children[3] is app._input_area.window
+    assert status_bar.style == "class:status-bar"
+    assert input_area is app._input_area.window
 
 
 def test_console_system_supports_visual_spacing() -> None: