runpane 2.3.0__tar.gz → 2.3.2__tar.gz

{runpane-2.3.0 → runpane-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runpane
-Version: 2.3.0
+Version: 2.3.2
 Summary: Thin PyPI installer and remote setup CLI for Pane
 Author-email: Dcouple Inc <hello@dcouple.ai>
 License: AGPL-3.0

{runpane-2.3.0 → runpane-2.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "runpane"
-version = "2.3.0"
+version = "2.3.2"
 description = "Thin PyPI installer and remote setup CLI for Pane"
 readme = "README.md"
 requires-python = ">=3.8"

runpane-2.3.2/src/runpane/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.3.2"

runpane-2.3.2/src/runpane/agent_context.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from .generated_contract import RUNPANE_CONTRACT
+
+
+def run_agent_context(parsed: Any) -> int:
+    result = build_agent_context_result(parsed.context_command)
+    if parsed.json:
+        print(json.dumps(result, indent=2))
+        return 0
+
+    if result["mode"] == "brief":
+        print(render_brief(result))
+    else:
+        print(render_command_detail(result["command"]))
+    return 0
+
+
+def build_agent_context_result(command_name: Optional[str] = None) -> Dict[str, Any]:
+    if command_name:
+        return {
+            "ok": True,
+            "mode": "command",
+            "source": "runpane-contract",
+            "command": get_command_detail(command_name),
+        }
+
+    brief = RUNPANE_CONTRACT["agentContext"]["brief"]
+    return {
+        "ok": True,
+        "mode": "brief",
+        "source": "runpane-contract",
+        "summary": brief["summary"],
+        "rules": brief["rules"],
+        "tools": brief["tools"],
+        "detailCommand": brief["detailCommand"],
+    }
+
+
+def get_command_detail(command_name: str) -> Dict[str, Any]:
+    for command in RUNPANE_CONTRACT["agentContext"]["commands"].values():
+        if command["name"] == command_name:
+            return command
+
+    raise ValueError(f"Unknown runpane command: {command_name}. Expected one of: {', '.join(command_names())}")
+
+
+def render_brief(result: Dict[str, Any]) -> str:
+    lines = [
+        RUNPANE_CONTRACT["agentContext"]["brief"]["title"],
+        "",
+        result["summary"],
+        "",
+        "Rules:",
+    ]
+    lines.extend(f"- {rule}" for rule in result["rules"])
+    lines.extend(["", "Tools:"])
+    for tool in result["tools"]:
+        lines.append(f"- {tool['name']}: {tool['summary']}")
+        lines.append(f"  Args: {', '.join(tool['arguments'])}")
+    lines.extend(["", f"Detailed definitions: {result['detailCommand']}"])
+    return "\n".join(lines)
+
+
+def render_command_detail(command: Dict[str, Any]) -> str:
+    lines = [
+        f"runpane {command['name']}",
+        "",
+        command["summary"],
+        "",
+        "Details:",
+        command["details"],
+        "",
+        f"Requires Pane daemon: {'yes' if command.get('requiresPaneDaemon') else 'no'}",
+        f"Mutates Pane state: {'yes' if command.get('mutates') else 'no'}",
+        "",
+        "Arguments:",
+    ]
+
+    if not command["arguments"]:
+        lines.append("- none")
+    else:
+        for argument in command["arguments"]:
+            value = f" {argument['value']}" if argument.get("value") else ""
+            required = "required" if argument["required"] else "optional"
+            lines.append(f"- {argument['name']}{value} ({required}): {argument['description']}")
+
+    lines.extend(["", "Examples:"])
+    lines.extend(f"- {example}" for example in command["examples"])
+
+    if command.get("jsonSchemas"):
+        lines.extend(["", "JSON schemas:"])
+        lines.extend(f"- {schema}" for schema in command["jsonSchemas"])
+
+    if command.get("notes"):
+        lines.extend(["", "Notes:"])
+        lines.extend(f"- {note}" for note in command["notes"])
+
+    return "\n".join(lines)
+
+
+def command_names() -> List[str]:
+    return sorted(
+        command["name"]
+        for command in RUNPANE_CONTRACT["agentContext"]["commands"].values()
+    )

{runpane-2.3.0 → runpane-2.3.2}/src/runpane/cli.py

@@ -4,8 +4,9 @@ from dataclasses import dataclass, field
 import os
 import socket
 import sys
-from typing import Dict, List, Optional, TypeVar
+from typing import Dict, List, Optional, Tuple, TypeVar
 
+from .agent_context import run_agent_context
 from .doctor import run_doctor
 from .download import download_artifact
 from .generated_contract import RUNPANE_CONTRACT
@@ -16,19 +17,35 @@ from .installers import (
     should_reuse_existing_pane,
     spawn_pane,
 )
+from .local_control import run_panes_create, run_repos_add, run_repos_list
 from .platforms import detect_platform
 from .releases import resolve_release
 from .version import print_version
 
 SOURCE = "pip"
 
-COMMANDS = {command["name"] for command in RUNPANE_CONTRACT["commands"]}
+COMMAND_MATCHERS = sorted(
+    ((command["name"], command["name"].split(" ")) for command in RUNPANE_CONTRACT["commands"]),
+    key=lambda item: len(item[1]),
+    reverse=True,
+)
 TARGETS = set(RUNPANE_CONTRACT["enums"]["installTargets"])
 FORMATS = set(RUNPANE_CONTRACT["enums"]["artifactFormats"])
 CHANNELS = set(RUNPANE_CONTRACT["enums"]["channels"])
+AGENTS = set(RUNPANE_CONTRACT["enums"]["agents"])
 
 REMOTE_VALUE_FLAGS = {flag["name"] for flag in RUNPANE_CONTRACT["flags"]["remoteValue"]}
 REMOTE_BOOLEAN_FLAGS = {flag["name"] for flag in RUNPANE_CONTRACT["flags"]["remoteBoolean"]}
+LOCAL_VALUE_FLAGS = {
+    value
+    for flag in RUNPANE_CONTRACT["flags"]["localValue"]
+    for value in [flag["name"], *flag.get("aliases", [])]
+}
+LOCAL_BOOLEAN_FLAGS = {
+    value
+    for flag in RUNPANE_CONTRACT["flags"]["localBoolean"]
+    for value in [flag["name"], *flag.get("aliases", [])]
+}
 DEFAULTS = RUNPANE_CONTRACT["defaults"]
 
 
@@ -44,6 +61,21 @@ class ParsedArgs:
     dry_run: bool = DEFAULTS["dryRun"]
     yes: bool = DEFAULTS["yes"]
     verbose: bool = DEFAULTS["verbose"]
+    json: bool = False
+    context_command: Optional[str] = None
+    pane_dir: Optional[str] = None
+    repo: Optional[str] = None
+    repo_path: Optional[str] = None
+    name: Optional[str] = None
+    worktree_name: Optional[str] = None
+    base_branch: Optional[str] = None
+    agent: Optional[str] = None
+    tool_command: Optional[str] = None
+    title: Optional[str] = None
+    initial_input: Optional[str] = None
+    initial_input_file: Optional[str] = None
+    from_json: Optional[str] = None
+    timeout_ms: Optional[float] = None
     help_topic: Optional[str] = None
     remote_setup_args: List[str] = field(default_factory=list)
 
@@ -64,6 +96,14 @@ def main(argv: Optional[List[str]] = None) -> int:
             return print_version(parsed.pane_path)
         if parsed.command == "doctor":
             return run_doctor(parsed, SOURCE)
+        if parsed.command == "agent-context":
+            return run_agent_context(parsed)
+        if parsed.command == "repos list":
+            return run_repos_list(parsed)
+        if parsed.command == "repos add":
+            return run_repos_add(parsed)
+        if parsed.command == "panes create":
+            return run_panes_create(parsed)
         if parsed.command in {"install", "update"}:
             return install_or_update(parsed)
         print(help_text(None))
@@ -192,15 +232,21 @@ def parse_args(argv: List[str]) -> ParsedArgs:
     args = list(argv)
     if not args or args[0] in {"-h", "--help"}:
         return ParsedArgs(command="help")
-    first = args.pop(0)
+    first = args[0]
     if first in {"-v", "--version"}:
         return ParsedArgs(command="version")
-    if first not in COMMANDS:
-        raise ValueError(f"Unknown command: {first}\n\n{help_text(None)}")
     if first == "help":
-        return ParsedArgs(command="help", help_topic=args[0] if args else None)
+        args.pop(0)
+        return ParsedArgs(command="help", help_topic=" ".join(args) or None)
+
+    matched = match_command(args)
+    if not matched:
+        raise ValueError(f"Unknown command: {first}\n\n{help_text(None)}")
 
-    parsed = ParsedArgs(command=first)
+    command, tokens = matched
+    del args[:len(tokens)]
+
+    parsed = ParsedArgs(command=command)
     if parsed.command == "install" and args and not args[0].startswith("-"):
         target = args.pop(0)
         if target not in TARGETS:
@@ -218,6 +264,8 @@ def parse_flags(args: List[str], parsed: ParsedArgs) -> None:
     index = 0
     while index < len(args):
         arg = args[index]
+        is_agent_context_command = parsed.command == "agent-context"
+        is_local_command = parsed.command in {"repos list", "repos add", "panes create"}
         if arg in {"-h", "--help"}:
             parsed.help_topic = parsed.command
             parsed.command = "help"
@@ -227,6 +275,16 @@ def parse_flags(args: List[str], parsed: ParsedArgs) -> None:
             parsed.yes = True
         elif arg == "--verbose":
             parsed.verbose = True
+        elif is_agent_context_command and arg == "--json":
+            parsed.json = True
+        elif is_agent_context_command and arg == "--command":
+            index += 1
+            parsed.context_command = read_value(args, index, arg)
+        elif is_local_command and arg in LOCAL_BOOLEAN_FLAGS:
+            parse_local_boolean_flag(parsed, arg)
+        elif is_local_command and arg in LOCAL_VALUE_FLAGS:
+            index += 1
+            parse_local_value_flag(parsed, arg, read_value(args, index, arg))
         elif arg == "--version":
             index += 1
             parsed.pane_version = read_value(args, index, arg)
@@ -262,6 +320,71 @@ def parse_flags(args: List[str], parsed: ParsedArgs) -> None:
         index += 1
 
 
+def match_command(args: List[str]) -> Optional[Tuple[str, List[str]]]:
+    for command, tokens in COMMAND_MATCHERS:
+        if args[:len(tokens)] == tokens:
+            return command, tokens
+    return None
+
+
+def parse_local_boolean_flag(parsed: ParsedArgs, flag: str) -> None:
+    if flag == "--json":
+        parsed.json = True
+        return
+    raise ValueError(f"Unknown option for {parsed.command}: {flag}")
+
+
+def parse_local_value_flag(parsed: ParsedArgs, flag: str, value: str) -> None:
+    if flag == "--pane-dir":
+        parsed.pane_dir = value
+        return
+    if flag == "--repo":
+        parsed.repo = value
+        return
+    if flag == "--path":
+        parsed.repo_path = value
+        return
+    if flag == "--name":
+        parsed.name = value
+        return
+    if flag == "--worktree-name":
+        parsed.worktree_name = value
+        return
+    if flag == "--base-branch":
+        parsed.base_branch = value
+        return
+    if flag == "--agent":
+        if value not in AGENTS:
+            raise ValueError(f"Invalid --agent {value}. Expected one of: {', '.join(sorted(AGENTS))}")
+        parsed.agent = value
+        return
+    if flag == "--tool-command":
+        parsed.tool_command = value
+        return
+    if flag == "--title":
+        parsed.title = value
+        return
+    if flag in {"--initial-input", "--prompt"}:
+        parsed.initial_input = value
+        return
+    if flag == "--initial-input-file":
+        parsed.initial_input_file = value
+        return
+    if flag == "--from-json":
+        parsed.from_json = value
+        return
+    if flag == "--timeout-ms":
+        try:
+            timeout_ms = float(value)
+        except ValueError as error:
+            raise ValueError("--timeout-ms must be a positive number.") from error
+        if timeout_ms <= 0:
+            raise ValueError("--timeout-ms must be a positive number.")
+        parsed.timeout_ms = timeout_ms
+        return
+    raise ValueError(f"Unknown option for {parsed.command}: {flag}")
+
+
 def append_remote_arg(parsed: ParsedArgs, flag: str, value: Optional[str] = None) -> None:
     if parsed.command == "install" and parsed.target == "daemon":
         parsed.remote_setup_args.append(flag)
@@ -272,7 +395,7 @@ def append_remote_arg(parsed: ParsedArgs, flag: str, value: Optional[str] = None
 
 
 def read_value(args: List[str], index: int, flag: str) -> str:
-    if index >= len(args) or args[index].startswith("-"):
+    if index >= len(args) or (args[index].startswith("-") and args[index] != "-"):
         raise ValueError(f"{flag} requires a value.")
     return args[index]
 

runpane-2.3.2/src/runpane/daemon_client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import ntpath
+import os
+import posixpath
+import socket
+import sys
+from typing import Any, Dict, List, Optional
+
+FRAME_DELIMITER = b"\n"
+UNIX_SOCKET_BASE_DIRECTORY = "/tmp"
+DAEMON_SOCKET_FILENAME = "daemon.sock"
+DEFAULT_TIMEOUT_MS = 130_000
+
+
+class PaneDaemonClientError(RuntimeError):
+    def __init__(self, message: str, code: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def resolve_pane_directory(pane_dir: Optional[str] = None) -> str:
+    return pane_dir or os.environ.get("PANE_DIR") or os.environ.get("FOOZOL_DIR") or os.path.join(os.path.expanduser("~"), ".pane")
+
+
+def get_pane_daemon_endpoint(app_directory: str, platform: str = sys.platform) -> Dict[str, str]:
+    resolved_app_directory = resolve_app_directory(app_directory, platform)
+    if platform.startswith("win"):
+        return {
+            "transport": "pipe",
+            "path": get_windows_pipe_name(resolved_app_directory),
+        }
+
+    return {
+        "transport": "unix",
+        "path": posixpath.join(get_unix_socket_directory_name(resolved_app_directory), DAEMON_SOCKET_FILENAME),
+    }
+
+
+def invoke_daemon(
+    channel: str,
+    args: Optional[List[Any]] = None,
+    pane_dir: Optional[str] = None,
+    timeout_ms: Optional[float] = None,
+) -> Any:
+    endpoint = get_pane_daemon_endpoint(resolve_pane_directory(pane_dir))
+    request = {
+        "type": "request",
+        "id": 1,
+        "channel": channel,
+        "args": args or [],
+    }
+    encoded = encode_frame(request)
+
+    if endpoint["transport"] == "pipe":
+        return invoke_windows_pipe(endpoint["path"], encoded, timeout_ms or DEFAULT_TIMEOUT_MS)
+    return invoke_unix_socket(endpoint["path"], encoded, timeout_ms or DEFAULT_TIMEOUT_MS)
+
+
+def invoke_unix_socket(socket_path: str, encoded_request: bytes, timeout_ms: float) -> Any:
+    decoder = PaneDaemonFrameDecoder()
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+        client.settimeout(timeout_ms / 1000)
+        try:
+            client.connect(socket_path)
+        except OSError as error:
+            raise PaneDaemonClientError(f"Could not connect to Pane daemon at {socket_path}: {error}") from error
+
+        client.sendall(encoded_request)
+        while True:
+            chunk = client.recv(65536)
+            if not chunk:
+                raise PaneDaemonClientError(
+                    f"Pane daemon closed the connection before responding at {socket_path}",
+                    "ERR_RUNPANE_DAEMON_CLOSED",
+                )
+            response = first_matching_response(decoder.push(chunk))
+            if response is not None:
+                return response
+
+
+def invoke_windows_pipe(pipe_path: str, encoded_request: bytes, timeout_ms: float) -> Any:
+    decoder = PaneDaemonFrameDecoder()
+    try:
+        with open(pipe_path, "r+b", buffering=0) as pipe:
+            pipe.write(encoded_request)
+            while True:
+                chunk = pipe.read(65536)
+                if not chunk:
+                    raise PaneDaemonClientError(
+                        f"Pane daemon closed the connection before responding at {pipe_path}",
+                        "ERR_RUNPANE_DAEMON_CLOSED",
+                    )
+                response = first_matching_response(decoder.push(chunk))
+                if response is not None:
+                    return response
+    except OSError as error:
+        raise PaneDaemonClientError(f"Could not connect to Pane daemon at {pipe_path}: {error}") from error
+
+
+def first_matching_response(frames: List[Dict[str, Any]]) -> Optional[Any]:
+    for frame in frames:
+        if frame.get("type") != "response" or frame.get("id") != 1:
+            continue
+        if frame.get("ok") is True:
+            return frame.get("result")
+        error = frame.get("error") or {}
+        raise PaneDaemonClientError(error.get("message", "Pane daemon request failed"), error.get("code"))
+    return None
+
+
+def resolve_app_directory(app_directory: str, platform: str) -> str:
+    if platform.startswith("win"):
+        return ntpath.abspath(app_directory)
+    return posixpath.abspath(app_directory)
+
+
+def get_windows_pipe_name(app_directory: str) -> str:
+    digest = hashlib.sha256(app_directory.lower().encode("utf-8")).hexdigest()[:16]
+    return "\\\\.\\pipe\\pane-daemon-" + digest
+
+
+def get_unix_socket_directory_name(app_directory: str) -> str:
+    digest = hashlib.sha256(app_directory.encode("utf-8")).hexdigest()[:16]
+    uid_suffix = f"-{os.getuid()}" if hasattr(os, "getuid") else ""
+    return posixpath.join(UNIX_SOCKET_BASE_DIRECTORY, f"pane-daemon{uid_suffix}-{digest}")
+
+
+def encode_frame(frame: Dict[str, Any]) -> bytes:
+    return json.dumps(frame, separators=(",", ":")).encode("utf-8") + FRAME_DELIMITER
+
+
+class PaneDaemonFrameDecoder:
+    def __init__(self) -> None:
+        self.buffer = b""
+
+    def push(self, chunk: bytes) -> List[Dict[str, Any]]:
+        self.buffer += chunk
+        frames: List[Dict[str, Any]] = []
+        while FRAME_DELIMITER in self.buffer:
+            raw_frame, self.buffer = self.buffer.split(FRAME_DELIMITER, 1)
+            if raw_frame.strip():
+                frames.append(json.loads(raw_frame.decode("utf-8")))
+        return frames

runpane-2.3.2/src/runpane/generated_contract.py

@@ -0,0 +1,4 @@
+# Generated by scripts/generate-runpane-contract.js. Do not edit by hand.
+import json
+
+RUNPANE_CONTRACT = json.loads("{\n  \"$schema\": \"./schema.json\",\n  \"schemaVersion\": 1,\n  \"name\": \"runpane\",\n  \"description\": \"Thin installer and local control CLI for Pane\",\n  \"packageInstallPolicy\": [\n    \"The packages must not download, install, or configure Pane during package installation.\",\n    \"Work starts only when a user runs `runpane ...`.\"\n  ],\n  \"compatibility\": {\n    \"node\": \">=18.17.0\",\n    \"python\": \">=3.8\"\n  },\n  \"terminology\": {\n    \"repo\": \"Saved Pane repository/project record\",\n    \"pane\": \"User-visible Pane session\",\n    \"tool\": \"Terminal-backed tab\",\n    \"agent\": \"Built-in agent command template\"\n  },\n  \"defaults\": {\n    \"target\": \"client\",\n    \"paneVersion\": \"latest\",\n    \"channel\": \"stable\",\n    \"format\": \"auto\",\n    \"dryRun\": false,\n    \"yes\": false,\n    \"verbose\": false\n  },\n  \"enums\": {\n    \"installTargets\": [\n      \"client\",\n      \"daemon\"\n    ],\n    \"artifactFormats\": [\n      \"auto\",\n      \"appimage\",\n      \"deb\",\n      \"dmg\",\n      \"zip\",\n      \"exe\"\n    ],\n    \"channels\": [\n      \"stable\",\n      \"nightly\"\n    ],\n    \"agents\": [\n      \"codex\",\n      \"claude\"\n    ]\n  },\n  \"agentTemplates\": {\n    \"codex\": {\n      \"title\": \"Codex\",\n      \"command\": \"codex --yolo\",\n      \"description\": \"Open a Codex terminal tab and allow the initial input to drive the agent.\"\n    },\n    \"claude\": {\n      \"title\": \"Claude Code\",\n      \"command\": \"claude --dangerously-skip-permissions\",\n      \"description\": \"Open a Claude Code terminal tab and allow the initial input to drive the agent.\"\n    }\n  },\n  \"commands\": [\n    {\n      \"name\": \"help\",\n      \"summary\": \"Show help for runpane or a specific command.\",\n      \"usage\": [\n        \"runpane help [command]\"\n      ]\n    },\n    {\n      \"name\": \"setup\",\n      \"summary\": \"Open the guided setup wizard for install, remote host setup, update, and diagnostics.\",\n      \"usage\": [\n        \"runpane setup\"\n      ],\n      \"interactiveEntrypoint\": true\n    },\n    {\n      \"name\": \"install\",\n      \"summary\": \"Install Pane on this machine or configure this machine as a remote daemon host.\",\n      \"usage\": [\n        \"runpane install [client|daemon] [options]\"\n      ],\n      \"defaultTarget\": \"client\",\n      \"targets\": [\n        \"client\",\n        \"daemon\"\n      ],\n      \"unknownDaemonFlagsForwarded\": true\n    },\n    {\n      \"name\": \"update\",\n      \"summary\": \"Update the Pane desktop app using the same artifact path as install client.\",\n      \"usage\": [\n        \"runpane update [options]\"\n      ],\n      \"target\": \"client\"\n    },\n    {\n      \"name\": \"version\",\n      \"summary\": \"Print the runpane wrapper version and installed Pane version when detectable.\",\n      \"usage\": [\n        \"runpane version\",\n        \"runpane --version\"\n      ]\n    },\n    {\n      \"name\": \"doctor\",\n      \"summary\": \"Run platform, release, installed Pane, and remote setup diagnostics.\",\n      \"usage\": [\n        \"runpane doctor\"\n      ]\n    },\n    {\n      \"name\": \"agent-context\",\n      \"summary\": \"Print token-efficient Pane command context for coding agents.\",\n      \"usage\": [\n        \"runpane agent-context [--json]\",\n        \"runpane agent-context --command <command> [--json]\"\n      ],\n      \"jsonSchemas\": [\n        \"agentContextBriefResult\",\n        \"agentContextCommandResult\"\n      ]\n    },\n    {\n      \"name\": \"repos list\",\n      \"summary\": \"List repositories saved in the running Pane app.\",\n      \"usage\": [\n        \"runpane repos list [--json] [--pane-dir <path>]\"\n      ],\n      \"jsonSchemas\": [\n        \"repoListResult\"\n      ]\n    },\n    {\n      \"name\": \"repos add\",\n      \"summary\": \"Register an existing git repository with the running Pane app.\",\n      \"usage\": [\n        \"runpane repos add --path <path> [--name <name>] [--json] [--yes]\"\n      ],\n      \"mutates\": true,\n      \"jsonSchemas\": [\n        \"repoAddRequest\",\n        \"repoAddResult\"\n      ]\n    },\n    {\n      \"name\": \"panes create\",\n      \"summary\": \"Create one or more Pane sessions in a saved repository and open a terminal-backed tool tab.\",\n      \"usage\": [\n        \"runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]\",\n        \"runpane panes create --from-json <path|-> [--yes] [--json]\"\n      ],\n      \"mutates\": true,\n      \"jsonSchemas\": [\n        \"paneCreateRequest\",\n        \"paneCreateResult\"\n      ]\n    }\n  ],\n  \"flags\": {\n    \"wrapper\": [\n      {\n        \"name\": \"--version\",\n        \"value\": \"<latest|vX.Y.Z>\",\n        \"description\": \"Pane release to install or inspect.\"\n      },\n      {\n        \"name\": \"--download-dir\",\n        \"value\": \"<path>\",\n        \"description\": \"Directory for downloaded Pane release artifacts.\"\n      },\n      {\n        \"name\": \"--pane-path\",\n        \"value\": \"<path>\",\n        \"description\": \"Use or inspect an existing Pane executable.\"\n      },\n      {\n        \"name\": \"--format\",\n        \"value\": \"<auto|appimage|deb|dmg|zip|exe>\",\n        \"description\": \"Pane release artifact format.\"\n      },\n      {\n        \"name\": \"--dry-run\",\n        \"description\": \"Print the plan without downloading or installing.\"\n      },\n      {\n        \"name\": \"--yes\",\n        \"aliases\": [\n          \"-y\"\n        ],\n        \"description\": \"Skip interactive prompts where possible.\"\n      },\n      {\n        \"name\": \"--verbose\",\n        \"description\": \"Print extra diagnostics.\"\n      }\n    ],\n    \"remoteValue\": [\n      {\n        \"name\": \"--label\",\n        \"value\": \"<name>\"\n      },\n      {\n        \"name\": \"--prefer-tunnel\",\n        \"value\": \"<tailscale|ssh|manual|auto>\"\n      },\n      {\n        \"name\": \"--channel\",\n        \"value\": \"<stable|nightly>\"\n      },\n      {\n        \"name\": \"--base-url\",\n        \"value\": \"<url>\"\n      },\n      {\n        \"name\": \"--pane-dir\",\n        \"value\": \"<path>\"\n      },\n      {\n        \"name\": \"--listen-port\",\n        \"value\": \"<port>\"\n      },\n      {\n        \"name\": \"--port\",\n        \"value\": \"<port>\"\n      },\n      {\n        \"name\": \"--repo-ref\",\n        \"value\": \"<ref>\"\n      }\n    ],\n    \"remoteBoolean\": [\n      {\n        \"name\": \"--auto-listen-port\"\n      },\n      {\n        \"name\": \"--interactive-tailscale-setup\"\n      },\n      {\n        \"name\": \"--no-install-service\"\n      },\n      {\n        \"name\": \"--no-tailscale-serve\"\n      },\n      {\n        \"name\": \"--print-only\"\n      }\n    ],\n    \"localValue\": [\n      {\n        \"name\": \"--pane-dir\",\n        \"value\": \"<path>\",\n        \"description\": \"Connect to a Pane daemon using this Pane data directory.\"\n      },\n      {\n        \"name\": \"--repo\",\n        \"value\": \"<selector>\",\n        \"description\": \"Repository selector: active, id, exact path, or saved repository name.\"\n      },\n      {\n        \"name\": \"--path\",\n        \"value\": \"<path>\",\n        \"description\": \"Existing git repository path to register with Pane.\"\n      },\n      {\n        \"name\": \"--name\",\n        \"value\": \"<name>\",\n        \"description\": \"Name for the registered repository or created pane/session.\"\n      },\n      {\n        \"name\": \"--worktree-name\",\n        \"value\": \"<name>\",\n        \"description\": \"Worktree name to request. Defaults to --name.\"\n      },\n      {\n        \"name\": \"--base-branch\",\n        \"value\": \"<branch>\",\n        \"description\": \"Base branch for the created worktree.\"\n      },\n      {\n        \"name\": \"--agent\",\n        \"value\": \"<codex|claude>\",\n        \"description\": \"Built-in agent terminal template to open.\"\n      },\n      {\n        \"name\": \"--tool-command\",\n        \"value\": \"<command>\",\n        \"description\": \"Custom terminal command to run instead of a built-in agent.\"\n      },\n      {\n        \"name\": \"--title\",\n        \"value\": \"<title>\",\n        \"description\": \"Terminal tab title. Defaults to the selected agent title or Terminal.\"\n      },\n      {\n        \"name\": \"--initial-input\",\n        \"value\": \"<text>\",\n        \"aliases\": [\n          \"--prompt\"\n        ],\n        \"description\": \"Text to send to the terminal after the command is ready. --prompt is an alias.\"\n      },\n      {\n        \"name\": \"--initial-input-file\",\n        \"value\": \"<path|->\",\n        \"description\": \"Read initial input from a file or stdin.\"\n      },\n      {\n        \"name\": \"--from-json\",\n        \"value\": \"<path|->\",\n        \"description\": \"Read a full panes.create request JSON payload from a file or stdin.\"\n      },\n      {\n        \"name\": \"--timeout-ms\",\n        \"value\": \"<milliseconds>\",\n        \"description\": \"Maximum time to wait for each pane creation job.\"\n      }\n    ],\n    \"localBoolean\": [\n      {\n        \"name\": \"--json\",\n        \"description\": \"Print machine-readable JSON output.\"\n      }\n    ]\n  },\n  \"help\": {\n    \"npm\": {\n      \"default\": [\n        \"Usage:\",\n        \"  runpane\",\n        \"  runpane setup\",\n        \"  runpane install [client|daemon] [options]\",\n        \"  runpane update [options]\",\n        \"  runpane version\",\n        \"  runpane doctor\",\n        \"  runpane agent-context [--json]\",\n        \"  runpane repos list [--json]\",\n        \"  runpane repos add --path <path> [--name <name>]\",\n        \"  runpane panes create --repo <selector> --name <name> --agent <codex|claude>\",\n        \"  runpane help [command]\",\n        \"\",\n        \"Quick start:\",\n        \"  npx --yes runpane@latest\",\n        \"  npm i -g runpane && runpane setup\",\n        \"\",\n        \"Advanced examples:\",\n        \"  npx --yes runpane@latest install client\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest\",\n        \"  pipx run runpane\",\n        \"\",\n        \"Run \\\"runpane agent-context\\\" when an agent needs Pane command context.\",\n        \"Run \\\"runpane help panes create\\\" for pane orchestration options.\"\n      ],\n      \"install\": [\n        \"Usage:\",\n        \"  runpane install [client|daemon] [options]\",\n        \"\",\n        \"Examples:\",\n        \"  npx --yes runpane@latest install client\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \\\"VM\\\"\",\n        \"\",\n        \"Wrapper options:\",\n        \"  --version <latest|vX.Y.Z>        Pane release to install\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>               Use an existing Pane executable\",\n        \"  --dry-run                       Print the plan without downloading\",\n        \"  --yes                           Skip interactive prompts where possible\",\n        \"  --verbose\",\n        \"\",\n        \"Daemon passthrough options:\",\n        \"  --label <name>\",\n        \"  --prefer-tunnel <tailscale|ssh|manual|auto>\",\n        \"  --channel <stable|nightly>\",\n        \"  --base-url <url>\",\n        \"  --pane-dir <path>\",\n        \"  --listen-port <port> / --port <port>\",\n        \"  --auto-listen-port\",\n        \"  --interactive-tailscale-setup\",\n        \"  --no-install-service\",\n        \"  --no-tailscale-serve\",\n        \"  --print-only\",\n        \"  --repo-ref <ref>\"\n      ],\n      \"setup\": [\n        \"Usage:\",\n        \"  runpane setup\",\n        \"\",\n        \"Opens the guided setup for desktop install, remote host setup, update, and diagnostics.\",\n        \"\",\n        \"Quick start:\",\n        \"  npx --yes runpane@latest\",\n        \"  npm i -g runpane && runpane setup\"\n      ],\n      \"update\": [\n        \"Usage:\",\n        \"  runpane update [options]\",\n        \"\",\n        \"Updates Pane using the same artifact selection as \\\"runpane install client\\\".\",\n        \"\",\n        \"Options:\",\n        \"  --version <latest|vX.Y.Z>\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>\",\n        \"  --dry-run\",\n        \"  --yes\",\n        \"  --verbose\"\n      ],\n      \"version\": [\n        \"Usage:\",\n        \"  runpane version\",\n        \"  runpane --version\"\n      ],\n      \"doctor\": [\n        \"Usage:\",\n        \"  runpane doctor [--pane-path <path>] [--format <format>] [--verbose]\"\n      ],\n      \"repos list\": [\n        \"Usage:\",\n        \"  runpane repos list [--json] [--pane-dir <path>]\",\n        \"\",\n        \"Lists repositories saved in the running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --json                         Print machine-readable output\",\n        \"  --pane-dir <path>              Connect to a specific Pane data directory\"\n      ],\n      \"repos add\": [\n        \"Usage:\",\n        \"  runpane repos add --path <path> [--name <name>] [--json] [--yes]\",\n        \"\",\n        \"Registers an existing git repository with the running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --path <path>                  Existing git repository path\",\n        \"  --name <name>                  Saved repository name; defaults to the directory name\",\n        \"  --pane-dir <path>              Connect to a specific Pane data directory\",\n        \"  --json                         Print machine-readable output\",\n        \"  --dry-run                      Validate and preview without adding the repo\",\n        \"  --yes                          Skip confirmation for mutating commands\"\n      ],\n      \"panes create\": [\n        \"Usage:\",\n        \"  runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]\",\n        \"  runpane panes create --from-json <path|-> [--yes] [--json]\",\n        \"\",\n        \"Creates Pane sessions in a saved repository and opens a terminal-backed tool tab.\",\n        \"\",\n        \"Options:\",\n        \"  --repo <selector>              active, id, exact path, or saved repository name\",\n        \"  --name <name>                  Pane/session name\",\n        \"  --worktree-name <name>         Worktree name; defaults to --name\",\n        \"  --base-branch <branch>         Base branch for the worktree\",\n        \"  --agent <codex|claude>         Built-in terminal template\",\n        \"  --tool-command <command>       Custom terminal command\",\n        \"  --title <title>                Terminal tab title\",\n        \"  --initial-input <text>         Text sent after the command is ready\",\n        \"  --prompt <text>                Alias for --initial-input\",\n        \"  --initial-input-file <path|->  Read initial input from a file or stdin\",\n        \"  --from-json <path|->           Read a full request payload\",\n        \"  --timeout-ms <milliseconds>    Pane creation timeout\",\n        \"  --pane-dir <path>              Connect to a specific Pane data directory\",\n        \"  --json                         Print machine-readable output\",\n        \"  --dry-run                      Validate and preview without creating panes\",\n        \"  --yes                          Skip confirmation for mutating commands\"\n      ],\n      \"agent-context\": [\n        \"Usage:\",\n        \"  runpane agent-context [--json]\",\n        \"  runpane agent-context --command <command> [--json]\",\n        \"\",\n        \"Prints Pane command context for coding agents without requiring a running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --command <command>            Print the full definition for one runpane command\",\n        \"  --json                         Print machine-readable output\",\n        \"\",\n        \"Examples:\",\n        \"  runpane agent-context\",\n        \"  runpane agent-context --json\",\n        \"  runpane agent-context --command \\\"panes create\\\"\",\n        \"  runpane agent-context --command \\\"panes create\\\" --json\"\n      ]\n    },\n    \"pip\": {\n      \"default\": [\n        \"Usage:\",\n        \"  runpane\",\n        \"  runpane setup\",\n        \"  runpane install [client|daemon] [options]\",\n        \"  runpane update [options]\",\n        \"  runpane version\",\n        \"  runpane doctor\",\n        \"  runpane agent-context [--json]\",\n        \"  runpane repos list [--json]\",\n        \"  runpane repos add --path <path> [--name <name>]\",\n        \"  runpane panes create --repo <selector> --name <name> --agent <codex|claude>\",\n        \"  runpane help [command]\",\n        \"\",\n        \"Quick start:\",\n        \"  pipx run runpane\",\n        \"  python -m pip install runpane && python -m runpane setup\",\n        \"\",\n        \"Advanced examples:\",\n        \"  pipx run runpane install client\",\n        \"  pipx run runpane install daemon --label \\\"My Server\\\"\",\n        \"  uvx runpane@latest\",\n        \"\",\n        \"Run \\\"runpane agent-context\\\" when an agent needs Pane command context.\",\n        \"Run \\\"runpane help panes create\\\" for pane orchestration options.\"\n      ],\n      \"install\": [\n        \"Usage:\",\n        \"  runpane install [client|daemon] [options]\",\n        \"\",\n        \"Examples:\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \\\"VM\\\"\",\n        \"  pipx run runpane install daemon --label \\\"My Server\\\"\",\n        \"\",\n        \"Wrapper options:\",\n        \"  --version <latest|vX.Y.Z>\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>\",\n        \"  --dry-run\",\n        \"  --yes\",\n        \"  --verbose\",\n        \"\",\n        \"Daemon passthrough options:\",\n        \"  --label <name>\",\n        \"  --prefer-tunnel <tailscale|ssh|manual|auto>\",\n        \"  --channel <stable|nightly>\",\n        \"  --base-url <url>\",\n        \"  --pane-dir <path>\",\n        \"  --listen-port <port> / --port <port>\",\n        \"  --auto-listen-port\",\n        \"  --interactive-tailscale-setup\",\n        \"  --no-install-service\",\n        \"  --no-tailscale-serve\",\n        \"  --print-only\",\n        \"  --repo-ref <ref>\"\n      ],\n      \"setup\": [\n        \"Usage:\",\n        \"  runpane setup\",\n        \"\",\n        \"Opens the guided setup for desktop install, remote host setup, update, and diagnostics.\",\n        \"\",\n        \"Quick start:\",\n        \"  pipx run runpane\",\n        \"  python -m pip install runpane && python -m runpane setup\"\n      ],\n      \"update\": [\n        \"Usage:\",\n        \"  runpane update [--version <latest|vX.Y.Z>] [--dry-run] [--yes]\"\n      ],\n      \"version\": [\n        \"Usage:\",\n        \"  runpane version\",\n        \"  runpane --version\"\n      ],\n      \"doctor\": [\n        \"Usage:\",\n        \"  runpane doctor [--pane-path <path>] [--format <format>] [--verbose]\"\n      ],\n      \"repos list\": [\n        \"Usage:\",\n        \"  runpane repos list [--json] [--pane-dir <path>]\",\n        \"\",\n        \"Lists repositories saved in the running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --json\",\n        \"  --pane-dir <path>\"\n      ],\n      \"repos add\": [\n        \"Usage:\",\n        \"  runpane repos add --path <path> [--name <name>] [--json] [--yes]\",\n        \"\",\n        \"Registers an existing git repository with the running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --path <path>\",\n        \"  --name <name>\",\n        \"  --pane-dir <path>\",\n        \"  --json\",\n        \"  --dry-run\",\n        \"  --yes\"\n      ],\n      \"panes create\": [\n        \"Usage:\",\n        \"  runpane panes create --repo <selector> --name <name> --agent <codex|claude> [options]\",\n        \"  runpane panes create --from-json <path|-> [--yes] [--json]\",\n        \"\",\n        \"Creates Pane sessions in a saved repository and opens a terminal-backed tool tab.\",\n        \"\",\n        \"Options:\",\n        \"  --repo <selector>\",\n        \"  --name <name>\",\n        \"  --worktree-name <name>\",\n        \"  --base-branch <branch>\",\n        \"  --agent <codex|claude>\",\n        \"  --tool-command <command>\",\n        \"  --title <title>\",\n        \"  --initial-input <text>\",\n        \"  --prompt <text>\",\n        \"  --initial-input-file <path|->\",\n        \"  --from-json <path|->\",\n        \"  --timeout-ms <milliseconds>\",\n        \"  --pane-dir <path>\",\n        \"  --json\",\n        \"  --dry-run\",\n        \"  --yes\"\n      ],\n      \"agent-context\": [\n        \"Usage:\",\n        \"  runpane agent-context [--json]\",\n        \"  runpane agent-context --command <command> [--json]\",\n        \"\",\n        \"Prints Pane command context for coding agents without requiring a running Pane app.\",\n        \"\",\n        \"Options:\",\n        \"  --command <command>\",\n        \"  --json\",\n        \"\",\n        \"Examples:\",\n        \"  runpane agent-context\",\n        \"  runpane agent-context --json\",\n        \"  runpane agent-context --command \\\"panes create\\\"\",\n        \"  runpane agent-context --command \\\"panes create\\\" --json\"\n      ]\n    }\n  },\n  \"docs\": {\n    \"maintainerRules\": [\n      \"Treat `contracts/runpane/contract.json` as the source of truth for both wrapper packages and generated docs.\",\n      \"Every command, flag, platform default, artifact-selection rule, and attribution rule change must be reflected in the contract.\",\n      \"The npm and PyPI wrappers must expose the same command behavior unless the contract explicitly documents a package-manager-specific difference.\",\n      \"Root `README.md` and package READMEs should lead with one guided quick-start command. Explicit commands, package-manager variants, and flags belong in an Advanced section.\",\n      \"Release version bumps must keep root `package.json`, `packages/runpane`, and `packages/runpane-py` versions in sync. Run `pnpm run check:runpane-package-versions` before release.\",\n      \"`pnpm run test:runpane-contract` must pass before changing wrapper command parsing, help output, platform defaults, release asset selection, or generated contract artifacts.\",\n      \"Token-based npm or PyPI publishing is a temporary fallback. Prefer trusted publishing once the package names are reserved and trusted publishers are configured.\"\n    ],\n    \"recommendedQuickStarts\": [\n      \"npx --yes runpane@latest\",\n      \"npm i -g runpane && runpane setup\",\n      \"pipx run runpane\",\n      \"python -m pip install runpane && python -m runpane setup\"\n    ],\n    \"npmCommands\": [\n      \"npx --yes runpane@latest\",\n      \"npx --yes runpane@latest setup\",\n      \"npx --yes runpane@latest install client\",\n      \"npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"pnpm dlx runpane@latest\",\n      \"pnpm dlx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"npm i -g runpane && runpane\",\n      \"npm i -g runpane && runpane setup\",\n      \"npm i -g runpane && runpane install daemon --label \\\"My Server\\\"\",\n      \"pnpm add -g runpane && runpane\",\n      \"pnpm add -g runpane && runpane setup\",\n      \"pnpm add -g runpane && runpane install daemon --label \\\"My Server\\\"\",\n      \"yarn dlx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"bunx runpane@latest install daemon --label \\\"My Server\\\"\"\n    ],\n    \"pythonCommands\": [\n      \"pipx run runpane\",\n      \"pipx run runpane setup\",\n      \"python -m pip install runpane\",\n      \"runpane\",\n      \"runpane setup\",\n      \"python -m runpane setup\",\n      \"runpane install daemon --label \\\"My Server\\\"\",\n      \"pipx install runpane\",\n      \"runpane\",\n      \"runpane setup\",\n      \"pipx run runpane install daemon --label \\\"My Server\\\"\",\n      \"uvx runpane@latest\",\n      \"uvx runpane@latest setup\",\n      \"uvx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"python -m runpane install daemon --label \\\"My Server\\\"\"\n    ],\n    \"packageManagerNotes\": [\n      \"Use `pnpm dlx` for one-shot pnpm execution and `pnpm add -g` for persistent CLI installation.\",\n      \"Do not document `pnpm install runpane` as the public CLI install path.\"\n    ],\n    \"commandUsages\": [\n      \"runpane\",\n      \"runpane setup\",\n      \"runpane install\",\n      \"runpane install client\",\n      \"runpane install daemon\",\n      \"runpane update\",\n      \"runpane version\",\n      \"runpane doctor\",\n      \"runpane agent-context\",\n      \"runpane agent-context --command \\\"panes create\\\" --json\",\n      \"runpane repos list --json\",\n      \"runpane repos add --path /path/to/repo --name Pane --yes --json\",\n      \"runpane panes create --repo active --name issue-252 --agent codex --prompt \\\"Kick off the discussion skill for issue 252\\\" --yes\",\n      \"runpane panes create --from-json panes.json --yes --json\",\n      \"runpane help\",\n      \"runpane <command> --help\"\n    ],\n    \"commandDescriptions\": [\n      \"`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. In non-interactive shells or CI, both forms must print help and exit successfully instead of waiting for input.\",\n      \"`runpane install` is an alias for `runpane install client`.\",\n      \"`runpane install client` downloads the selected Pane desktop artifact and installs, opens, or launches it for the current platform.\",\n      \"`runpane install daemon` downloads or installs Pane, resolves a stable Pane executable path, and spawns `<pane executable> --remote-setup <forwarded remote setup args>`.\",\n      \"The wrapper must stream Pane stdout/stderr without reformatting because `pane --remote-setup` prints the one-time `pane-remote://...` connection code.\",\n      \"`runpane update` uses the same release resolution and installer path as `install client`.\",\n      \"`runpane version` prints the wrapper package version, the installed Pane version when detectable, and the latest GitHub release version when reachable.\",\n      \"`runpane doctor` checks platform support, release metadata reachability, download URL selection, installed Pane detection, and remote-daemon hints.\",\n      \"`runpane agent-context` prints a brief, token-efficient command schema for coding agents without connecting to the Pane daemon.\",\n      \"`runpane agent-context --command \\\"panes create\\\"` prints the detailed definition for one command. Add `--json` for machine-readable output.\",\n      \"`runpane repos list` connects to the running local Pane daemon and prints saved repository records.\",\n      \"`runpane repos add` registers an existing git repository with the running local Pane daemon. It does not create directories or initialize git repositories by default.\",\n      \"`runpane panes create` connects to the running local Pane daemon, resolves the requested repository, creates Pane sessions, opens terminal-backed tool tabs, and optionally sends initial input to the started tool.\",\n      \"`runpane panes create --prompt` is an alias for `--initial-input`; request JSON and daemon payloads should use the canonical `initialInput` field.\"\n    ],\n    \"wrapperFlagNote\": \"The top-level `runpane --version` form prints the wrapper version. The install subcommand form `runpane install --version vX.Y.Z` selects a Pane release.\",\n    \"localControlFlagNote\": \"`runpane repos list` and `runpane panes create` use the local framed daemon socket/pipe for a running Pane app. `--pane-dir` points the wrapper at a non-default Pane data directory, such as `PANE_DIR=~/.pane_test` in development. `runpane agent-context` is local/offline and can be used before Pane is running.\",\n    \"daemonFlagNote\": \"Unknown daemon flags should be forwarded rather than dropped so newer Pane versions can extend `--remote-setup` without requiring an immediate wrapper release. Unknown flags for non-daemon commands should fail clearly.\",\n    \"downloadAttribution\": [\n      \"The npm package uses `source=npm` for all npm-registry consumers, including `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, and global npm/pnpm installs.\",\n      \"The PyPI package uses `source=pip` for all Python consumers, including pip, pipx, uvx, and `python -m runpane`.\",\n      \"Wrappers should prefer `https://runpane.com/api/download?platform=<platform>&arch=<arch>&format=<format>&version=<version>&channel=<channel>&source=<npm|pip>`.\",\n      \"If the website route cannot satisfy the download, wrappers may fall back to the matching GitHub release asset and print a warning that website attribution may be incomplete for that run.\"\n    ],\n    \"publishingCredentials\": [\n      \"Local implementation, build, and dry-run validation do not need npm or PyPI API tokens.\",\n      \"Release publishing should prefer npm Trusted Publishing and PyPI Trusted Publishing from GitHub Actions.\",\n      \"Fallback `NPM_TOKEN` or `PYPI_API_TOKEN` credentials may be used for first package reservation or manual publication only. They must be supplied through local environment variables or GitHub Actions secrets, never committed, and revoked or rotated after use.\"\n    ]\n  },\n  \"testFixtures\": {\n    \"parserSamples\": [\n      [\n        \"setup\"\n      ],\n      [\n        \"install\"\n      ],\n      [\n        \"install\",\n        \"client\",\n        \"--version\",\n        \"v2.2.8\",\n        \"--format\",\n        \"dmg\",\n        \"--download-dir\",\n        \"/tmp/pane-downloads\",\n        \"--dry-run\",\n        \"--yes\"\n      ],\n      [\n        \"install\",\n        \"daemon\",\n        \"--label\",\n        \"VM\",\n        \"--prefer-tunnel\",\n        \"ssh\",\n        \"--channel\",\n        \"nightly\",\n        \"--base-url\",\n        \"https://example.test\",\n        \"--pane-dir\",\n        \"/tmp/pane\",\n        \"--listen-port\",\n        \"4555\",\n        \"--auto-listen-port\",\n        \"--print-only\",\n        \"--repo-ref\",\n        \"main\",\n        \"--unknown-future-flag\",\n        \"future-value\",\n        \"--dry-run\",\n        \"--verbose\"\n      ],\n      [\n        \"update\",\n        \"--version\",\n        \"latest\",\n        \"--format\",\n        \"appimage\",\n        \"--pane-path\",\n        \"/usr/bin/pane\",\n        \"--dry-run\"\n      ],\n      [\n        \"doctor\",\n        \"--pane-path\",\n        \"/usr/bin/pane\",\n        \"--format\",\n        \"zip\",\n        \"--verbose\"\n      ],\n      [\n        \"agent-context\"\n      ],\n      [\n        \"agent-context\",\n        \"--command\",\n        \"panes create\",\n        \"--json\"\n      ],\n      [\n        \"repos\",\n        \"list\",\n        \"--json\",\n        \"--pane-dir\",\n        \"/tmp/pane\"\n      ],\n      [\n        \"repos\",\n        \"add\",\n        \"--path\",\n        \"/tmp/repo\",\n        \"--name\",\n        \"Repo\",\n        \"--dry-run\",\n        \"--yes\",\n        \"--json\",\n        \"--pane-dir\",\n        \"/tmp/pane\"\n      ],\n      [\n        \"panes\",\n        \"create\",\n        \"--repo\",\n        \"active\",\n        \"--name\",\n        \"issue-252\",\n        \"--agent\",\n        \"codex\",\n        \"--prompt\",\n        \"Kick off discussion\",\n        \"--dry-run\",\n        \"--yes\",\n        \"--json\"\n      ],\n      [\n        \"panes\",\n        \"create\",\n        \"--from-json\",\n        \"-\",\n        \"--yes\",\n        \"--json\"\n      ],\n      [\n        \"--version\"\n      ]\n    ],\n    \"topLevelHelpIncludes\": [\n      \"runpane setup\",\n      \"runpane install\",\n      \"runpane update\",\n      \"runpane version\",\n      \"runpane doctor\",\n      \"runpane agent-context\",\n      \"runpane repos list\",\n      \"runpane repos add\",\n      \"runpane panes create\"\n    ],\n    \"npmHelpIncludes\": [\n      \"pnpm dlx runpane@latest\",\n      \"npx --yes runpane@latest\"\n    ],\n    \"pipHelpIncludes\": [\n      \"pipx run runpane\",\n      \"python -m pip install runpane && python -m runpane setup\"\n    ],\n    \"installHelpIncludes\": [\n      \"--version <latest|vX.Y.Z>\",\n      \"--format <auto|appimage|deb|dmg|zip|exe>\",\n      \"--download-dir <path>\",\n      \"--pane-path <path>\",\n      \"--label <name>\",\n      \"--prefer-tunnel <tailscale|ssh|manual|auto>\",\n      \"--repo-ref <ref>\"\n    ]\n  },\n  \"jsonSchemas\": {\n    \"error\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"error\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": false\n        },\n        \"error\": {\n          \"type\": \"object\",\n          \"required\": [\n            \"message\"\n          ],\n          \"properties\": {\n            \"message\": {\n              \"type\": \"string\"\n            },\n            \"code\": {\n              \"type\": \"string\"\n            }\n          },\n          \"additionalProperties\": false\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"repoListResult\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"repos\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": true\n        },\n        \"repos\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\n              \"id\",\n              \"name\",\n              \"path\",\n              \"active\",\n              \"sessionCount\"\n            ],\n            \"properties\": {\n              \"id\": {\n                \"type\": \"number\"\n              },\n              \"name\": {\n                \"type\": \"string\"\n              },\n              \"path\": {\n                \"type\": \"string\"\n              },\n              \"active\": {\n                \"type\": \"boolean\"\n              },\n              \"environment\": {\n                \"type\": \"string\"\n              },\n              \"sessionCount\": {\n                \"type\": \"number\"\n              }\n            },\n            \"additionalProperties\": false\n          }\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"repoAddRequest\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"path\"\n      ],\n      \"properties\": {\n        \"path\": {\n          \"type\": \"string\"\n        },\n        \"name\": {\n          \"type\": \"string\"\n        },\n        \"dryRun\": {\n          \"type\": \"boolean\"\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"repoAddResult\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"created\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": true\n        },\n        \"created\": {\n          \"type\": \"boolean\"\n        },\n        \"dryRun\": {\n          \"type\": \"boolean\"\n        },\n        \"repo\": {\n          \"$ref\": \"#/jsonSchemas/repoListResult/properties/repos/items\"\n        },\n        \"preview\": {\n          \"type\": \"object\",\n          \"required\": [\n            \"name\",\n            \"path\",\n            \"alreadyExists\",\n            \"wouldCreate\"\n          ],\n          \"properties\": {\n            \"name\": {\n              \"type\": \"string\"\n            },\n            \"path\": {\n              \"type\": \"string\"\n            },\n            \"alreadyExists\": {\n              \"type\": \"boolean\"\n            },\n            \"wouldCreate\": {\n              \"type\": \"boolean\"\n            },\n            \"environment\": {\n              \"type\": \"string\"\n            }\n          },\n          \"additionalProperties\": false\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"paneCreateRequest\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"repo\",\n        \"panes\"\n      ],\n      \"properties\": {\n        \"repo\": {\n          \"oneOf\": [\n            {\n              \"type\": \"string\"\n            },\n            {\n              \"type\": \"object\",\n              \"properties\": {\n                \"id\": {\n                  \"type\": \"number\"\n                },\n                \"path\": {\n                  \"type\": \"string\"\n                },\n                \"name\": {\n                  \"type\": \"string\"\n                },\n                \"active\": {\n                  \"const\": true\n                }\n              },\n              \"additionalProperties\": false\n            }\n          ]\n        },\n        \"panes\": {\n          \"type\": \"array\",\n          \"minItems\": 1,\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\n              \"name\",\n              \"tool\"\n            ],\n            \"properties\": {\n              \"name\": {\n                \"type\": \"string\"\n              },\n              \"worktreeName\": {\n                \"type\": \"string\"\n              },\n              \"baseBranch\": {\n                \"type\": \"string\"\n              },\n              \"sessionPrompt\": {\n                \"type\": \"string\"\n              },\n              \"tool\": {\n                \"oneOf\": [\n                  {\n                    \"type\": \"object\",\n                    \"required\": [\n                      \"agent\"\n                    ],\n                    \"properties\": {\n                      \"agent\": {\n                        \"enum\": [\n                          \"codex\",\n                          \"claude\"\n                        ]\n                      },\n                      \"title\": {\n                        \"type\": \"string\"\n                      },\n                      \"initialInput\": {\n                        \"type\": \"string\"\n                      }\n                    },\n                    \"additionalProperties\": false\n                  },\n                  {\n                    \"type\": \"object\",\n                    \"required\": [\n                      \"command\"\n                    ],\n                    \"properties\": {\n                      \"command\": {\n                        \"type\": \"string\"\n                      },\n                      \"title\": {\n                        \"type\": \"string\"\n                      },\n                      \"initialInput\": {\n                        \"type\": \"string\"\n                      }\n                    },\n                    \"additionalProperties\": false\n                  }\n                ]\n              }\n            },\n            \"additionalProperties\": false\n          }\n        },\n        \"dryRun\": {\n          \"type\": \"boolean\"\n        },\n        \"timeoutMs\": {\n          \"type\": \"number\"\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"paneCreateResult\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"repo\",\n        \"items\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"type\": \"boolean\"\n        },\n        \"repo\": {\n          \"$ref\": \"#/jsonSchemas/repoListResult/properties/repos/items\"\n        },\n        \"items\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"oneOf\": [\n              {\n                \"type\": \"object\",\n                \"required\": [\n                  \"ok\",\n                  \"index\",\n                  \"name\"\n                ],\n                \"properties\": {\n                  \"ok\": {\n                    \"const\": true\n                  },\n                  \"index\": {\n                    \"type\": \"number\"\n                  },\n                  \"name\": {\n                    \"type\": \"string\"\n                  },\n                  \"sessionId\": {\n                    \"type\": \"string\"\n                  },\n                  \"paneId\": {\n                    \"type\": \"string\"\n                  },\n                  \"panelId\": {\n                    \"type\": \"string\"\n                  },\n                  \"worktreePath\": {\n                    \"type\": \"string\"\n                  },\n                  \"tool\": {\n                    \"type\": \"object\",\n                    \"required\": [\n                      \"title\",\n                      \"command\"\n                    ],\n                    \"properties\": {\n                      \"title\": {\n                        \"type\": \"string\"\n                      },\n                      \"command\": {\n                        \"type\": \"string\"\n                      },\n                      \"agent\": {\n                        \"enum\": [\n                          \"codex\",\n                          \"claude\"\n                        ]\n                      }\n                    },\n                    \"additionalProperties\": false\n                  }\n                },\n                \"additionalProperties\": false\n              },\n              {\n                \"type\": \"object\",\n                \"required\": [\n                  \"ok\",\n                  \"index\",\n                  \"error\"\n                ],\n                \"properties\": {\n                  \"ok\": {\n                    \"const\": false\n                  },\n                  \"index\": {\n                    \"type\": \"number\"\n                  },\n                  \"name\": {\n                    \"type\": \"string\"\n                  },\n                  \"error\": {\n                    \"type\": \"object\",\n                    \"required\": [\n                      \"message\"\n                    ],\n                    \"properties\": {\n                      \"message\": {\n                        \"type\": \"string\"\n                      },\n                      \"code\": {\n                        \"type\": \"string\"\n                      }\n                    },\n                    \"additionalProperties\": false\n                  }\n                },\n                \"additionalProperties\": false\n              }\n            ]\n          }\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"agentContextBriefResult\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"mode\",\n        \"source\",\n        \"summary\",\n        \"rules\",\n        \"tools\",\n        \"detailCommand\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": true\n        },\n        \"mode\": {\n          \"const\": \"brief\"\n        },\n        \"source\": {\n          \"const\": \"runpane-contract\"\n        },\n        \"summary\": {\n          \"type\": \"string\"\n        },\n        \"rules\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"string\"\n          }\n        },\n        \"tools\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\n              \"name\",\n              \"summary\",\n              \"arguments\"\n            ],\n            \"properties\": {\n              \"name\": {\n                \"type\": \"string\"\n              },\n              \"summary\": {\n                \"type\": \"string\"\n              },\n              \"arguments\": {\n                \"type\": \"array\",\n                \"items\": {\n                  \"type\": \"string\"\n                }\n              }\n            },\n            \"additionalProperties\": false\n          }\n        },\n        \"detailCommand\": {\n          \"type\": \"string\"\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"agentContextCommandResult\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"mode\",\n        \"source\",\n        \"command\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": true\n        },\n        \"mode\": {\n          \"const\": \"command\"\n        },\n        \"source\": {\n          \"const\": \"runpane-contract\"\n        },\n        \"command\": {\n          \"type\": \"object\",\n          \"required\": [\n            \"name\",\n            \"summary\",\n            \"details\",\n            \"arguments\",\n            \"examples\"\n          ],\n          \"properties\": {\n            \"name\": {\n              \"type\": \"string\"\n            },\n            \"summary\": {\n              \"type\": \"string\"\n            },\n            \"details\": {\n              \"type\": \"string\"\n            },\n            \"requiresPaneDaemon\": {\n              \"type\": \"boolean\"\n            },\n            \"mutates\": {\n              \"type\": \"boolean\"\n            },\n            \"arguments\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"object\"\n              }\n            },\n            \"examples\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"string\"\n              }\n            },\n            \"jsonSchemas\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"string\"\n              }\n            },\n            \"notes\": {\n              \"type\": \"array\",\n              \"items\": {\n                \"type\": \"string\"\n              }\n            }\n          },\n          \"additionalProperties\": false\n        }\n      },\n      \"additionalProperties\": false\n    }\n  },\n  \"agentContext\": {\n    \"brief\": {\n      \"title\": \"Pane agent context\",\n      \"summary\": \"Pane lets a developer manage repositories and user-visible panes. Agents can use runpane to list/add Pane repositories and create panes with terminal-backed tools.\",\n      \"rules\": [\n        \"Start with `runpane repos list --json` to find the saved repository when unsure.\",\n        \"If the repository exists on disk but is not saved in Pane, use `runpane repos add --path <repo> --yes --json` before creating panes.\",\n        \"Use `runpane panes create` to create a Pane session and open a built-in agent or custom terminal command.\",\n        \"Use `runpane agent-context --command <command>` for detailed command definitions only when needed.\"\n      ],\n      \"detailCommand\": \"runpane agent-context --command <command> [--json]\",\n      \"tools\": [\n        {\n          \"name\": \"agent-context\",\n          \"summary\": \"Print token-efficient Pane command context for coding agents.\",\n          \"arguments\": [\n            \"--command <command>\",\n            \"--json\"\n          ]\n        },\n        {\n          \"name\": \"repos list\",\n          \"summary\": \"List repositories saved in the running Pane app.\",\n          \"arguments\": [\n            \"--json\",\n            \"--pane-dir <path>\"\n          ]\n        },\n        {\n          \"name\": \"repos add\",\n          \"summary\": \"Register an existing git repository with the running Pane app.\",\n          \"arguments\": [\n            \"--path <path>\",\n            \"--name <name>\",\n            \"--yes\",\n            \"--json\",\n            \"--dry-run\",\n            \"--pane-dir <path>\"\n          ]\n        },\n        {\n          \"name\": \"panes create\",\n          \"summary\": \"Create one or more Pane sessions in a saved repository and open a terminal-backed tool tab.\",\n          \"arguments\": [\n            \"--repo <selector>\",\n            \"--name <name>\",\n            \"--agent <codex|claude>\",\n            \"--tool-command <command>\",\n            \"--prompt <text>\",\n            \"--from-json <path|->\",\n            \"--yes\",\n            \"--json\"\n          ]\n        }\n      ]\n    },\n    \"commands\": {\n      \"help\": {\n        \"name\": \"help\",\n        \"summary\": \"Show help for runpane or a specific command.\",\n        \"details\": \"Use this when you need human-readable usage text for a command.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": false,\n        \"arguments\": [\n          {\n            \"name\": \"command\",\n            \"value\": \"<command>\",\n            \"required\": false,\n            \"description\": \"Optional command topic such as \\\"panes create\\\".\"\n          }\n        ],\n        \"examples\": [\n          \"runpane help\",\n          \"runpane help panes create\"\n        ],\n        \"notes\": [\n          \"Help text is generated from the runpane contract.\"\n        ]\n      },\n      \"setup\": {\n        \"name\": \"setup\",\n        \"summary\": \"Open the guided setup wizard for install, remote host setup, update, and diagnostics.\",\n        \"details\": \"Use this for a human-driven Pane setup flow, not for unattended agent orchestration.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": false,\n        \"arguments\": [],\n        \"examples\": [\n          \"runpane setup\"\n        ],\n        \"notes\": [\n          \"In non-interactive shells, setup prints help and exits successfully.\"\n        ]\n      },\n      \"install\": {\n        \"name\": \"install\",\n        \"summary\": \"Install Pane on this machine or configure this machine as a remote daemon host.\",\n        \"details\": \"Installs or launches Pane release artifacts at command runtime. `install daemon` forwards remote setup flags to Pane.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": true,\n        \"arguments\": [\n          {\n            \"name\": \"target\",\n            \"value\": \"<client|daemon>\",\n            \"required\": false,\n            \"description\": \"Install the desktop client or configure a remote daemon host.\"\n          },\n          {\n            \"name\": \"--version\",\n            \"value\": \"<latest|vX.Y.Z>\",\n            \"required\": false,\n            \"description\": \"Pane release to install.\"\n          },\n          {\n            \"name\": \"--format\",\n            \"value\": \"<auto|appimage|deb|dmg|zip|exe>\",\n            \"required\": false,\n            \"description\": \"Release artifact format.\"\n          },\n          {\n            \"name\": \"--yes\",\n            \"required\": false,\n            \"description\": \"Skip interactive prompts where possible.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane install client\",\n          \"runpane install daemon --label \\\"My Server\\\"\"\n        ],\n        \"notes\": [\n          \"Package install itself is inert; work begins only when runpane is executed.\"\n        ]\n      },\n      \"update\": {\n        \"name\": \"update\",\n        \"summary\": \"Update the Pane desktop app using the same artifact path as install client.\",\n        \"details\": \"Resolves and installs the selected Pane client release.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": true,\n        \"arguments\": [\n          {\n            \"name\": \"--version\",\n            \"value\": \"<latest|vX.Y.Z>\",\n            \"required\": false,\n            \"description\": \"Pane release to update to.\"\n          },\n          {\n            \"name\": \"--format\",\n            \"value\": \"<auto|appimage|deb|dmg|zip|exe>\",\n            \"required\": false,\n            \"description\": \"Release artifact format.\"\n          },\n          {\n            \"name\": \"--dry-run\",\n            \"required\": false,\n            \"description\": \"Print the update plan without downloading.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane update\",\n          \"runpane update --version latest\"\n        ],\n        \"notes\": [\n          \"Equivalent artifact selection to `runpane install client`.\"\n        ]\n      },\n      \"version\": {\n        \"name\": \"version\",\n        \"summary\": \"Print the runpane wrapper version and installed Pane version when detectable.\",\n        \"details\": \"Use this for diagnostics or to confirm which wrapper is available.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": false,\n        \"arguments\": [\n          {\n            \"name\": \"--pane-path\",\n            \"value\": \"<path>\",\n            \"required\": false,\n            \"description\": \"Inspect a specific Pane executable.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane version\",\n          \"runpane --version\"\n        ],\n        \"notes\": []\n      },\n      \"doctor\": {\n        \"name\": \"doctor\",\n        \"summary\": \"Run platform, release, installed Pane, and remote setup diagnostics.\",\n        \"details\": \"Use this when runpane install/update behavior needs environment diagnostics.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": false,\n        \"arguments\": [\n          {\n            \"name\": \"--pane-path\",\n            \"value\": \"<path>\",\n            \"required\": false,\n            \"description\": \"Use an existing Pane executable for diagnostics.\"\n          },\n          {\n            \"name\": \"--verbose\",\n            \"required\": false,\n            \"description\": \"Print extra diagnostics.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane doctor\",\n          \"runpane doctor --verbose\"\n        ],\n        \"notes\": []\n      },\n      \"agent-context\": {\n        \"name\": \"agent-context\",\n        \"summary\": \"Print token-efficient Pane command context for coding agents.\",\n        \"details\": \"Use this first when an agent needs to discover Pane primitives. It is local/offline and does not require a running Pane app.\",\n        \"requiresPaneDaemon\": false,\n        \"mutates\": false,\n        \"arguments\": [\n          {\n            \"name\": \"--command\",\n            \"value\": \"<command>\",\n            \"required\": false,\n            \"description\": \"Print the detailed definition for one command, for example \\\"panes create\\\".\"\n          },\n          {\n            \"name\": \"--json\",\n            \"required\": false,\n            \"description\": \"Print machine-readable output.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane agent-context\",\n          \"runpane agent-context --command \\\"panes create\\\" --json\"\n        ],\n        \"jsonSchemas\": [\n          \"agentContextBriefResult\",\n          \"agentContextCommandResult\"\n        ],\n        \"notes\": [\n          \"Default output is brief so AGENTS.md can point here without bloating context.\"\n        ]\n      },\n      \"repos list\": {\n        \"name\": \"repos list\",\n        \"summary\": \"List repositories saved in the running Pane app.\",\n        \"details\": \"Use this to find the right Pane-managed repository before creating panes. If the repo is missing, use `repos add` first.\",\n        \"requiresPaneDaemon\": true,\n        \"mutates\": false,\n        \"arguments\": [\n          {\n            \"name\": \"--json\",\n            \"required\": false,\n            \"description\": \"Print machine-readable repository records.\"\n          },\n          {\n            \"name\": \"--pane-dir\",\n            \"value\": \"<path>\",\n            \"required\": false,\n            \"description\": \"Connect to a specific Pane data directory.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane repos list --json\"\n        ],\n        \"jsonSchemas\": [\n          \"repoListResult\"\n        ],\n        \"notes\": [\n          \"Requires a running Pane app or daemon for the selected Pane data directory.\"\n        ]\n      },\n      \"repos add\": {\n        \"name\": \"repos add\",\n        \"summary\": \"Register an existing git repository with the running Pane app.\",\n        \"details\": \"Use this when the repository exists on disk but is not saved in Pane yet. It validates the path as a git repository.\",\n        \"requiresPaneDaemon\": true,\n        \"mutates\": true,\n        \"arguments\": [\n          {\n            \"name\": \"--path\",\n            \"value\": \"<path>\",\n            \"required\": true,\n            \"description\": \"Existing git repository path to register with Pane.\"\n          },\n          {\n            \"name\": \"--name\",\n            \"value\": \"<name>\",\n            \"required\": false,\n            \"description\": \"Saved repository name; defaults to the directory name.\"\n          },\n          {\n            \"name\": \"--yes\",\n            \"required\": false,\n            \"description\": \"Skip confirmation for mutating commands.\"\n          },\n          {\n            \"name\": \"--json\",\n            \"required\": false,\n            \"description\": \"Print machine-readable output.\"\n          },\n          {\n            \"name\": \"--dry-run\",\n            \"required\": false,\n            \"description\": \"Validate and preview without adding the repo.\"\n          },\n          {\n            \"name\": \"--pane-dir\",\n            \"value\": \"<path>\",\n            \"required\": false,\n            \"description\": \"Connect to a specific Pane data directory.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane repos add --path /path/to/repo --yes --json\"\n        ],\n        \"jsonSchemas\": [\n          \"repoAddRequest\",\n          \"repoAddResult\"\n        ],\n        \"notes\": [\n          \"It does not create directories or initialize git repositories by default.\"\n        ]\n      },\n      \"panes create\": {\n        \"name\": \"panes create\",\n        \"summary\": \"Create one or more Pane sessions in a saved repository and open a terminal-backed tool tab.\",\n        \"details\": \"Use this to set up user-visible panes for work. Select a saved repository, choose a built-in agent or custom terminal command, and optionally send initial input after the tool starts.\",\n        \"requiresPaneDaemon\": true,\n        \"mutates\": true,\n        \"arguments\": [\n          {\n            \"name\": \"--repo\",\n            \"value\": \"<selector>\",\n            \"required\": true,\n            \"description\": \"Repository selector: active, id, exact path, or saved repository name.\"\n          },\n          {\n            \"name\": \"--name\",\n            \"value\": \"<name>\",\n            \"required\": true,\n            \"description\": \"Pane/session name.\"\n          },\n          {\n            \"name\": \"--agent\",\n            \"value\": \"<codex|claude>\",\n            \"required\": false,\n            \"description\": \"Built-in agent terminal template to open.\"\n          },\n          {\n            \"name\": \"--tool-command\",\n            \"value\": \"<command>\",\n            \"required\": false,\n            \"description\": \"Custom terminal command to run instead of a built-in agent.\"\n          },\n          {\n            \"name\": \"--prompt\",\n            \"value\": \"<text>\",\n            \"required\": false,\n            \"description\": \"Alias for --initial-input; sends text after the command is ready.\"\n          },\n          {\n            \"name\": \"--initial-input-file\",\n            \"value\": \"<path|->\",\n            \"required\": false,\n            \"description\": \"Read initial input from a file or stdin.\"\n          },\n          {\n            \"name\": \"--from-json\",\n            \"value\": \"<path|->\",\n            \"required\": false,\n            \"description\": \"Read a full panes.create request JSON payload.\"\n          },\n          {\n            \"name\": \"--yes\",\n            \"required\": false,\n            \"description\": \"Skip confirmation for mutating commands.\"\n          },\n          {\n            \"name\": \"--json\",\n            \"required\": false,\n            \"description\": \"Print machine-readable output.\"\n          }\n        ],\n        \"examples\": [\n          \"runpane panes create --repo active --name issue-257 --agent codex --prompt \\\"Plan this issue\\\" --yes\",\n          \"runpane panes create --from-json panes.json --yes --json\"\n        ],\n        \"jsonSchemas\": [\n          \"paneCreateRequest\",\n          \"paneCreateResult\"\n        ],\n        \"notes\": [\n          \"At least one of --agent or --tool-command is required unless --from-json is used.\",\n          \"The built-in agent templates come from the runpane contract; custom terminal commands can pass agent-specific flags when requested by the user.\"\n        ]\n      }\n    },\n    \"managedBlock\": [\n      \"## Pane\",\n      \"\",\n      \"The developer is using Pane for this repository. Pane can manage saved repositories and create user-visible panes with terminal-backed tools for planning, discussion, and implementation work.\",\n      \"\",\n      \"Use `runpane agent-context` for a brief Pane command schema. Use `runpane agent-context --command \\\"panes create\\\"` or another command name for the detailed schema only when needed.\",\n      \"\",\n      \"Common commands:\",\n      \"- `runpane repos list --json`\",\n      \"- `runpane repos add --path <repo> --yes --json`\",\n      \"- `runpane panes create --repo active --name <name> --agent codex --prompt \\\"<task>\\\" --yes`\"\n    ]\n  }\n}")

runpane-2.3.2/src/runpane/local_control.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any, Dict, Optional
+
+from .daemon_client import invoke_daemon
+from .generated_contract import RUNPANE_CONTRACT
+
+
+def run_repos_list(parsed: Any) -> int:
+    result = invoke_daemon("runpane:repos:list", pane_dir=parsed.pane_dir)
+
+    if parsed.json:
+        print_json(result)
+        return 0
+
+    repos = result.get("repos", [])
+    if not repos:
+        print("No Pane repositories found.")
+        return 0
+
+    for repo in repos:
+        marker = "*" if repo.get("active") else " "
+        environment = f" {repo.get('environment')}" if repo.get("environment") else ""
+        print(f"{marker} {repo.get('id')}\t{repo.get('name')}\t{repo.get('path')}\t{repo.get('sessionCount')} sessions{environment}")
+    return 0
+
+
+def run_repos_add(parsed: Any) -> int:
+    request = build_repo_add_request(parsed)
+    confirm_repo_add(parsed, request)
+    result = invoke_daemon("runpane:repos:add", [request], pane_dir=parsed.pane_dir)
+
+    if parsed.json:
+        print_json(result)
+    else:
+        print_repo_add_result(result)
+
+    return 0
+
+
+def run_panes_create(parsed: Any) -> int:
+    request = build_pane_create_request(parsed)
+    confirm_pane_create(parsed, request)
+    result = invoke_daemon(
+        "runpane:panes:create",
+        [request],
+        pane_dir=parsed.pane_dir,
+        timeout_ms=(parsed.timeout_ms or 120_000) + 10_000,
+    )
+
+    if parsed.json:
+        print_json(result)
+    else:
+        print_pane_create_result(result)
+
+    return 0 if result.get("ok") else 1
+
+
+def build_repo_add_request(parsed: Any) -> Dict[str, Any]:
+    if not parsed.repo_path:
+        raise ValueError("runpane repos add requires --path.")
+
+    return {
+        "path": parsed.repo_path,
+        **optional_value("name", parsed.name),
+        **optional_value("dryRun", True if parsed.dry_run else None),
+    }
+
+
+def build_pane_create_request(parsed: Any) -> Dict[str, Any]:
+    if parsed.from_json:
+        payload = json.loads(read_input_source(parsed.from_json))
+        if not isinstance(payload, dict):
+            raise ValueError("--from-json payload must be an object.")
+        if parsed.dry_run:
+            payload["dryRun"] = True
+        if parsed.timeout_ms is not None:
+            payload["timeoutMs"] = parsed.timeout_ms
+        return payload
+
+    if not parsed.repo:
+        raise ValueError("runpane panes create requires --repo unless --from-json is used.")
+    if not parsed.name:
+        raise ValueError("runpane panes create requires --name unless --from-json is used.")
+
+    return {
+        "repo": parsed.repo,
+        "panes": [{
+            "name": parsed.name,
+            **optional_value("worktreeName", parsed.worktree_name),
+            **optional_value("baseBranch", parsed.base_branch),
+            "tool": build_tool_spec(parsed),
+        }],
+        **optional_value("dryRun", True if parsed.dry_run else None),
+        **optional_value("timeoutMs", parsed.timeout_ms),
+    }
+
+
+def build_tool_spec(parsed: Any) -> Dict[str, Any]:
+    if parsed.agent and parsed.tool_command:
+        raise ValueError("Use either --agent or --tool-command, not both.")
+
+    initial_input = resolve_initial_input(parsed)
+    agent = parsed.agent
+
+    if not agent and not parsed.tool_command:
+        if not is_interactive_shell():
+            raise ValueError("runpane panes create requires --agent or --tool-command in non-interactive shells.")
+        agent = ask_agent_choice()
+
+    if agent:
+        return {
+            "agent": agent,
+            **optional_value("title", parsed.title),
+            **optional_value("initialInput", initial_input),
+        }
+
+    if not parsed.tool_command:
+        raise ValueError("runpane panes create requires --agent or --tool-command.")
+
+    return {
+        "command": parsed.tool_command,
+        **optional_value("title", parsed.title),
+        **optional_value("initialInput", initial_input),
+    }
+
+
+def resolve_initial_input(parsed: Any) -> Optional[str]:
+    if parsed.initial_input and parsed.initial_input_file:
+        raise ValueError("Use either --initial-input/--prompt or --initial-input-file, not both.")
+    if parsed.initial_input_file:
+        return read_input_source(parsed.initial_input_file)
+    return parsed.initial_input
+
+
+def confirm_repo_add(parsed: Any, request: Dict[str, Any]) -> None:
+    if parsed.dry_run or parsed.yes:
+        return
+    if not is_interactive_shell():
+        raise ValueError("runpane repos add mutates Pane state. Rerun with --yes in non-interactive shells.")
+
+    label = f"{request.get('name')} at {request.get('path')}" if request.get("name") else request.get("path")
+    answer = input(f"Add Pane repo {label}? [y/N] ").strip().lower()
+    if answer not in {"y", "yes"}:
+        raise ValueError("Cancelled.")
+
+
+def confirm_pane_create(parsed: Any, request: Dict[str, Any]) -> None:
+    if parsed.dry_run or parsed.yes:
+        return
+    if not is_interactive_shell():
+        raise ValueError("runpane panes create mutates Pane state. Rerun with --yes in non-interactive shells.")
+
+    count = len(request.get("panes", []))
+    answer = input(f"Create {count} Pane pane{'s' if count != 1 else ''}? [y/N] ").strip().lower()
+    if answer not in {"y", "yes"}:
+        raise ValueError("Cancelled.")
+
+
+def ask_agent_choice() -> str:
+    agents = RUNPANE_CONTRACT["enums"]["agents"]
+    print("Choose an agent:")
+    for index, agent in enumerate(agents, start=1):
+        print(f"{index}) {RUNPANE_CONTRACT['agentTemplates'][agent]['title']}")
+
+    while True:
+        answer = input("Agent [1]: ").strip().lower()
+        if not answer:
+            return agents[0]
+        if answer.isdigit() and 1 <= int(answer) <= len(agents):
+            return agents[int(answer) - 1]
+        if answer in agents:
+            return answer
+        print(f"Choose one of: {', '.join(agents)}")
+
+
+def read_input_source(source: str) -> str:
+    if source == "-":
+        return sys.stdin.read()
+    with open(source, "r", encoding="utf-8") as handle:
+        return handle.read()
+
+
+def print_json(value: Any) -> None:
+    print(json.dumps(value, indent=2))
+
+
+def print_repo_add_result(result: Dict[str, Any]) -> None:
+    preview = result.get("preview") or {}
+    if result.get("dryRun") and preview:
+        if preview.get("alreadyExists"):
+            print(f"Repo already exists: {preview.get('name')}\t{preview.get('path')}")
+            return
+        print(f"Would add Pane repo {preview.get('name')}\t{preview.get('path')}")
+        return
+
+    repo = result.get("repo")
+    if repo:
+        action = "Added Pane repo" if result.get("created") else "Repo already exists"
+        print(f"{action}: {repo.get('id')}\t{repo.get('name')}\t{repo.get('path')}")
+        return
+
+    print("Repo add completed.")
+
+
+def print_pane_create_result(result: Dict[str, Any]) -> None:
+    for item in result.get("items", []):
+        name = item.get("name") or f"pane {item.get('index')}"
+        if item.get("ok"):
+            worktree = f" at {item.get('worktreePath')}" if item.get("worktreePath") else ""
+            print(f"Created {name}: session {item.get('sessionId', 'unknown')} panel {item.get('panelId', 'unknown')}{worktree}")
+        else:
+            error = item.get("error") or {}
+            print(f"Failed {name}: {error.get('message', 'unknown error')}", file=sys.stderr)
+
+
+def optional_value(key: str, value: Any) -> Dict[str, Any]:
+    return {key: value} if value is not None else {}
+
+
+def is_interactive_shell() -> bool:
+    return bool(sys.stdin.isatty() and sys.stdout.isatty() and not os.environ.get("CI"))

{runpane-2.3.0 → runpane-2.3.2}/src/runpane.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: runpane
-Version: 2.3.0
+Version: 2.3.2
 Summary: Thin PyPI installer and remote setup CLI for Pane
 Author-email: Dcouple Inc <hello@dcouple.ai>
 License: AGPL-3.0

{runpane-2.3.0 → runpane-2.3.2}/src/runpane.egg-info/SOURCES.txt

@@ -2,11 +2,14 @@ README.md
 pyproject.toml
 src/runpane/__init__.py
 src/runpane/__main__.py
+src/runpane/agent_context.py
 src/runpane/cli.py
+src/runpane/daemon_client.py
 src/runpane/doctor.py
 src/runpane/download.py
 src/runpane/generated_contract.py
 src/runpane/installers.py
+src/runpane/local_control.py
 src/runpane/platforms.py
 src/runpane/releases.py
 src/runpane/version.py

runpane-2.3.0/src/runpane/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.3.0"

runpane-2.3.0/src/runpane/generated_contract.py

@@ -1,4 +0,0 @@
-# Generated by scripts/generate-runpane-contract.js. Do not edit by hand.
-import json
-
-RUNPANE_CONTRACT = json.loads("{\n  \"$schema\": \"./schema.json\",\n  \"schemaVersion\": 1,\n  \"name\": \"runpane\",\n  \"description\": \"Thin installer and local control CLI for Pane\",\n  \"packageInstallPolicy\": [\n    \"The packages must not download, install, or configure Pane during package installation.\",\n    \"Work starts only when a user runs `runpane ...`.\"\n  ],\n  \"compatibility\": {\n    \"node\": \">=18.17.0\",\n    \"python\": \">=3.8\"\n  },\n  \"terminology\": {\n    \"repo\": \"Saved Pane repository/project record\",\n    \"pane\": \"User-visible Pane session\",\n    \"tool\": \"Terminal-backed tab\",\n    \"agent\": \"Built-in agent command template\"\n  },\n  \"defaults\": {\n    \"target\": \"client\",\n    \"paneVersion\": \"latest\",\n    \"channel\": \"stable\",\n    \"format\": \"auto\",\n    \"dryRun\": false,\n    \"yes\": false,\n    \"verbose\": false\n  },\n  \"enums\": {\n    \"installTargets\": [\n      \"client\",\n      \"daemon\"\n    ],\n    \"artifactFormats\": [\n      \"auto\",\n      \"appimage\",\n      \"deb\",\n      \"dmg\",\n      \"zip\",\n      \"exe\"\n    ],\n    \"channels\": [\n      \"stable\",\n      \"nightly\"\n    ]\n  },\n  \"commands\": [\n    {\n      \"name\": \"help\",\n      \"summary\": \"Show help for runpane or a specific command.\",\n      \"usage\": [\n        \"runpane help [command]\"\n      ]\n    },\n    {\n      \"name\": \"setup\",\n      \"summary\": \"Open the guided setup wizard for install, remote host setup, update, and diagnostics.\",\n      \"usage\": [\n        \"runpane setup\"\n      ],\n      \"interactiveEntrypoint\": true\n    },\n    {\n      \"name\": \"install\",\n      \"summary\": \"Install Pane on this machine or configure this machine as a remote daemon host.\",\n      \"usage\": [\n        \"runpane install [client|daemon] [options]\"\n      ],\n      \"defaultTarget\": \"client\",\n      \"targets\": [\n        \"client\",\n        \"daemon\"\n      ],\n      \"unknownDaemonFlagsForwarded\": true\n    },\n    {\n      \"name\": \"update\",\n      \"summary\": \"Update the Pane desktop app using the same artifact path as install client.\",\n      \"usage\": [\n        \"runpane update [options]\"\n      ],\n      \"target\": \"client\"\n    },\n    {\n      \"name\": \"version\",\n      \"summary\": \"Print the runpane wrapper version and installed Pane version when detectable.\",\n      \"usage\": [\n        \"runpane version\",\n        \"runpane --version\"\n      ]\n    },\n    {\n      \"name\": \"doctor\",\n      \"summary\": \"Run platform, release, installed Pane, and remote setup diagnostics.\",\n      \"usage\": [\n        \"runpane doctor\"\n      ]\n    }\n  ],\n  \"flags\": {\n    \"wrapper\": [\n      {\n        \"name\": \"--version\",\n        \"value\": \"<latest|vX.Y.Z>\",\n        \"description\": \"Pane release to install or inspect.\"\n      },\n      {\n        \"name\": \"--download-dir\",\n        \"value\": \"<path>\",\n        \"description\": \"Directory for downloaded Pane release artifacts.\"\n      },\n      {\n        \"name\": \"--pane-path\",\n        \"value\": \"<path>\",\n        \"description\": \"Use or inspect an existing Pane executable.\"\n      },\n      {\n        \"name\": \"--format\",\n        \"value\": \"<auto|appimage|deb|dmg|zip|exe>\",\n        \"description\": \"Pane release artifact format.\"\n      },\n      {\n        \"name\": \"--dry-run\",\n        \"description\": \"Print the plan without downloading or installing.\"\n      },\n      {\n        \"name\": \"--yes\",\n        \"aliases\": [\n          \"-y\"\n        ],\n        \"description\": \"Skip interactive prompts where possible.\"\n      },\n      {\n        \"name\": \"--verbose\",\n        \"description\": \"Print extra diagnostics.\"\n      }\n    ],\n    \"remoteValue\": [\n      {\n        \"name\": \"--label\",\n        \"value\": \"<name>\"\n      },\n      {\n        \"name\": \"--prefer-tunnel\",\n        \"value\": \"<tailscale|ssh|manual|auto>\"\n      },\n      {\n        \"name\": \"--channel\",\n        \"value\": \"<stable|nightly>\"\n      },\n      {\n        \"name\": \"--base-url\",\n        \"value\": \"<url>\"\n      },\n      {\n        \"name\": \"--pane-dir\",\n        \"value\": \"<path>\"\n      },\n      {\n        \"name\": \"--listen-port\",\n        \"value\": \"<port>\"\n      },\n      {\n        \"name\": \"--port\",\n        \"value\": \"<port>\"\n      },\n      {\n        \"name\": \"--repo-ref\",\n        \"value\": \"<ref>\"\n      }\n    ],\n    \"remoteBoolean\": [\n      {\n        \"name\": \"--auto-listen-port\"\n      },\n      {\n        \"name\": \"--interactive-tailscale-setup\"\n      },\n      {\n        \"name\": \"--no-install-service\"\n      },\n      {\n        \"name\": \"--no-tailscale-serve\"\n      },\n      {\n        \"name\": \"--print-only\"\n      }\n    ]\n  },\n  \"help\": {\n    \"npm\": {\n      \"default\": [\n        \"Usage:\",\n        \"  runpane\",\n        \"  runpane setup\",\n        \"  runpane install [client|daemon] [options]\",\n        \"  runpane update [options]\",\n        \"  runpane version\",\n        \"  runpane doctor\",\n        \"  runpane help [command]\",\n        \"\",\n        \"Quick start:\",\n        \"  npx --yes runpane@latest\",\n        \"  npm i -g runpane && runpane setup\",\n        \"\",\n        \"Advanced examples:\",\n        \"  npx --yes runpane@latest install client\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest\",\n        \"  pipx run runpane\",\n        \"\",\n        \"Run \\\"runpane help install\\\" for install options.\"\n      ],\n      \"install\": [\n        \"Usage:\",\n        \"  runpane install [client|daemon] [options]\",\n        \"\",\n        \"Examples:\",\n        \"  npx --yes runpane@latest install client\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \\\"VM\\\"\",\n        \"\",\n        \"Wrapper options:\",\n        \"  --version <latest|vX.Y.Z>        Pane release to install\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>               Use an existing Pane executable\",\n        \"  --dry-run                       Print the plan without downloading\",\n        \"  --yes                           Skip interactive prompts where possible\",\n        \"  --verbose\",\n        \"\",\n        \"Daemon passthrough options:\",\n        \"  --label <name>\",\n        \"  --prefer-tunnel <tailscale|ssh|manual|auto>\",\n        \"  --channel <stable|nightly>\",\n        \"  --base-url <url>\",\n        \"  --pane-dir <path>\",\n        \"  --listen-port <port> / --port <port>\",\n        \"  --auto-listen-port\",\n        \"  --interactive-tailscale-setup\",\n        \"  --no-install-service\",\n        \"  --no-tailscale-serve\",\n        \"  --print-only\",\n        \"  --repo-ref <ref>\"\n      ],\n      \"setup\": [\n        \"Usage:\",\n        \"  runpane setup\",\n        \"\",\n        \"Opens the guided setup for desktop install, remote host setup, update, and diagnostics.\",\n        \"\",\n        \"Quick start:\",\n        \"  npx --yes runpane@latest\",\n        \"  npm i -g runpane && runpane setup\"\n      ],\n      \"update\": [\n        \"Usage:\",\n        \"  runpane update [options]\",\n        \"\",\n        \"Updates Pane using the same artifact selection as \\\"runpane install client\\\".\",\n        \"\",\n        \"Options:\",\n        \"  --version <latest|vX.Y.Z>\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>\",\n        \"  --dry-run\",\n        \"  --yes\",\n        \"  --verbose\"\n      ],\n      \"version\": [\n        \"Usage:\",\n        \"  runpane version\",\n        \"  runpane --version\"\n      ],\n      \"doctor\": [\n        \"Usage:\",\n        \"  runpane doctor [--pane-path <path>] [--format <format>] [--verbose]\"\n      ]\n    },\n    \"pip\": {\n      \"default\": [\n        \"Usage:\",\n        \"  runpane\",\n        \"  runpane setup\",\n        \"  runpane install [client|daemon] [options]\",\n        \"  runpane update [options]\",\n        \"  runpane version\",\n        \"  runpane doctor\",\n        \"  runpane help [command]\",\n        \"\",\n        \"Quick start:\",\n        \"  pipx run runpane\",\n        \"  python -m pip install runpane && python -m runpane setup\",\n        \"\",\n        \"Advanced examples:\",\n        \"  pipx run runpane install client\",\n        \"  pipx run runpane install daemon --label \\\"My Server\\\"\",\n        \"  uvx runpane@latest\",\n        \"\",\n        \"Run \\\"runpane help install\\\" for install options.\"\n      ],\n      \"install\": [\n        \"Usage:\",\n        \"  runpane install [client|daemon] [options]\",\n        \"\",\n        \"Examples:\",\n        \"  npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n        \"  pnpm dlx runpane@latest install daemon --prefer-tunnel ssh --label \\\"VM\\\"\",\n        \"  pipx run runpane install daemon --label \\\"My Server\\\"\",\n        \"\",\n        \"Wrapper options:\",\n        \"  --version <latest|vX.Y.Z>\",\n        \"  --format <auto|appimage|deb|dmg|zip|exe>\",\n        \"  --download-dir <path>\",\n        \"  --pane-path <path>\",\n        \"  --dry-run\",\n        \"  --yes\",\n        \"  --verbose\",\n        \"\",\n        \"Daemon passthrough options:\",\n        \"  --label <name>\",\n        \"  --prefer-tunnel <tailscale|ssh|manual|auto>\",\n        \"  --channel <stable|nightly>\",\n        \"  --base-url <url>\",\n        \"  --pane-dir <path>\",\n        \"  --listen-port <port> / --port <port>\",\n        \"  --auto-listen-port\",\n        \"  --interactive-tailscale-setup\",\n        \"  --no-install-service\",\n        \"  --no-tailscale-serve\",\n        \"  --print-only\",\n        \"  --repo-ref <ref>\"\n      ],\n      \"setup\": [\n        \"Usage:\",\n        \"  runpane setup\",\n        \"\",\n        \"Opens the guided setup for desktop install, remote host setup, update, and diagnostics.\",\n        \"\",\n        \"Quick start:\",\n        \"  pipx run runpane\",\n        \"  python -m pip install runpane && python -m runpane setup\"\n      ],\n      \"update\": [\n        \"Usage:\",\n        \"  runpane update [--version <latest|vX.Y.Z>] [--dry-run] [--yes]\"\n      ],\n      \"version\": [\n        \"Usage:\",\n        \"  runpane version\",\n        \"  runpane --version\"\n      ],\n      \"doctor\": [\n        \"Usage:\",\n        \"  runpane doctor [--pane-path <path>] [--format <format>] [--verbose]\"\n      ]\n    }\n  },\n  \"docs\": {\n    \"maintainerRules\": [\n      \"Treat `contracts/runpane/contract.json` as the source of truth for both wrapper packages and generated docs.\",\n      \"Every command, flag, platform default, artifact-selection rule, and attribution rule change must be reflected in the contract.\",\n      \"The npm and PyPI wrappers must expose the same command behavior unless the contract explicitly documents a package-manager-specific difference.\",\n      \"Root `README.md` and package READMEs should lead with one guided quick-start command. Explicit commands, package-manager variants, and flags belong in an Advanced section.\",\n      \"Release version bumps must keep root `package.json`, `packages/runpane`, and `packages/runpane-py` versions in sync. Run `pnpm run check:runpane-package-versions` before release.\",\n      \"`pnpm run test:runpane-contract` must pass before changing wrapper command parsing, help output, platform defaults, release asset selection, or generated contract artifacts.\",\n      \"Token-based npm or PyPI publishing is a temporary fallback. Prefer trusted publishing once the package names are reserved and trusted publishers are configured.\"\n    ],\n    \"recommendedQuickStarts\": [\n      \"npx --yes runpane@latest\",\n      \"npm i -g runpane && runpane setup\",\n      \"pipx run runpane\",\n      \"python -m pip install runpane && python -m runpane setup\"\n    ],\n    \"npmCommands\": [\n      \"npx --yes runpane@latest\",\n      \"npx --yes runpane@latest setup\",\n      \"npx --yes runpane@latest install client\",\n      \"npx --yes runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"pnpm dlx runpane@latest\",\n      \"pnpm dlx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"npm i -g runpane && runpane\",\n      \"npm i -g runpane && runpane setup\",\n      \"npm i -g runpane && runpane install daemon --label \\\"My Server\\\"\",\n      \"pnpm add -g runpane && runpane\",\n      \"pnpm add -g runpane && runpane setup\",\n      \"pnpm add -g runpane && runpane install daemon --label \\\"My Server\\\"\",\n      \"yarn dlx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"bunx runpane@latest install daemon --label \\\"My Server\\\"\"\n    ],\n    \"pythonCommands\": [\n      \"pipx run runpane\",\n      \"pipx run runpane setup\",\n      \"python -m pip install runpane\",\n      \"runpane\",\n      \"runpane setup\",\n      \"python -m runpane setup\",\n      \"runpane install daemon --label \\\"My Server\\\"\",\n      \"pipx install runpane\",\n      \"runpane\",\n      \"runpane setup\",\n      \"pipx run runpane install daemon --label \\\"My Server\\\"\",\n      \"uvx runpane@latest\",\n      \"uvx runpane@latest setup\",\n      \"uvx runpane@latest install daemon --label \\\"My Server\\\"\",\n      \"python -m runpane install daemon --label \\\"My Server\\\"\"\n    ],\n    \"packageManagerNotes\": [\n      \"Use `pnpm dlx` for one-shot pnpm execution and `pnpm add -g` for persistent CLI installation.\",\n      \"Do not document `pnpm install runpane` as the public CLI install path.\"\n    ],\n    \"commandUsages\": [\n      \"runpane\",\n      \"runpane setup\",\n      \"runpane install\",\n      \"runpane install client\",\n      \"runpane install daemon\",\n      \"runpane update\",\n      \"runpane version\",\n      \"runpane doctor\",\n      \"runpane help\",\n      \"runpane <command> --help\"\n    ],\n    \"commandDescriptions\": [\n      \"`runpane` with no arguments and `runpane setup` open an interactive wizard when stdin and stdout are TTYs. In non-interactive shells or CI, both forms must print help and exit successfully instead of waiting for input.\",\n      \"`runpane install` is an alias for `runpane install client`.\",\n      \"`runpane install client` downloads the selected Pane desktop artifact and installs, opens, or launches it for the current platform.\",\n      \"`runpane install daemon` downloads or installs Pane, resolves a stable Pane executable path, and spawns `<pane executable> --remote-setup <forwarded remote setup args>`.\",\n      \"The wrapper must stream Pane stdout/stderr without reformatting because `pane --remote-setup` prints the one-time `pane-remote://...` connection code.\",\n      \"`runpane update` uses the same release resolution and installer path as `install client`.\",\n      \"`runpane version` prints the wrapper package version, the installed Pane version when detectable, and the latest GitHub release version when reachable.\",\n      \"`runpane doctor` checks platform support, release metadata reachability, download URL selection, installed Pane detection, and remote-daemon hints.\"\n    ],\n    \"wrapperFlagNote\": \"The top-level `runpane --version` form prints the wrapper version. The install subcommand form `runpane install --version vX.Y.Z` selects a Pane release.\",\n    \"daemonFlagNote\": \"Unknown daemon flags should be forwarded rather than dropped so newer Pane versions can extend `--remote-setup` without requiring an immediate wrapper release. Unknown flags for non-daemon commands should fail clearly.\",\n    \"downloadAttribution\": [\n      \"The npm package uses `source=npm` for all npm-registry consumers, including `npx`, `pnpm dlx`, `yarn dlx`, `bunx`, and global npm/pnpm installs.\",\n      \"The PyPI package uses `source=pip` for all Python consumers, including pip, pipx, uvx, and `python -m runpane`.\",\n      \"Wrappers should prefer `https://runpane.com/api/download?platform=<platform>&arch=<arch>&format=<format>&version=<version>&channel=<channel>&source=<npm|pip>`.\",\n      \"If the website route cannot satisfy the download, wrappers may fall back to the matching GitHub release asset and print a warning that website attribution may be incomplete for that run.\"\n    ],\n    \"publishingCredentials\": [\n      \"Local implementation, build, and dry-run validation do not need npm or PyPI API tokens.\",\n      \"Release publishing should prefer npm Trusted Publishing and PyPI Trusted Publishing from GitHub Actions.\",\n      \"Fallback `NPM_TOKEN` or `PYPI_API_TOKEN` credentials may be used for first package reservation or manual publication only. They must be supplied through local environment variables or GitHub Actions secrets, never committed, and revoked or rotated after use.\"\n    ]\n  },\n  \"testFixtures\": {\n    \"parserSamples\": [\n      [\n        \"setup\"\n      ],\n      [\n        \"install\"\n      ],\n      [\n        \"install\",\n        \"client\",\n        \"--version\",\n        \"v2.2.8\",\n        \"--format\",\n        \"dmg\",\n        \"--download-dir\",\n        \"/tmp/pane-downloads\",\n        \"--dry-run\",\n        \"--yes\"\n      ],\n      [\n        \"install\",\n        \"daemon\",\n        \"--label\",\n        \"VM\",\n        \"--prefer-tunnel\",\n        \"ssh\",\n        \"--channel\",\n        \"nightly\",\n        \"--base-url\",\n        \"https://example.test\",\n        \"--pane-dir\",\n        \"/tmp/pane\",\n        \"--listen-port\",\n        \"4555\",\n        \"--auto-listen-port\",\n        \"--print-only\",\n        \"--repo-ref\",\n        \"main\",\n        \"--unknown-future-flag\",\n        \"future-value\",\n        \"--dry-run\",\n        \"--verbose\"\n      ],\n      [\n        \"update\",\n        \"--version\",\n        \"latest\",\n        \"--format\",\n        \"appimage\",\n        \"--pane-path\",\n        \"/usr/bin/pane\",\n        \"--dry-run\"\n      ],\n      [\n        \"doctor\",\n        \"--pane-path\",\n        \"/usr/bin/pane\",\n        \"--format\",\n        \"zip\",\n        \"--verbose\"\n      ],\n      [\n        \"--version\"\n      ]\n    ],\n    \"topLevelHelpIncludes\": [\n      \"runpane setup\",\n      \"runpane install\",\n      \"runpane update\",\n      \"runpane version\",\n      \"runpane doctor\"\n    ],\n    \"npmHelpIncludes\": [\n      \"pnpm dlx runpane@latest\",\n      \"npx --yes runpane@latest\"\n    ],\n    \"pipHelpIncludes\": [\n      \"pipx run runpane\",\n      \"python -m pip install runpane && python -m runpane setup\"\n    ],\n    \"installHelpIncludes\": [\n      \"--version <latest|vX.Y.Z>\",\n      \"--format <auto|appimage|deb|dmg|zip|exe>\",\n      \"--download-dir <path>\",\n      \"--pane-path <path>\",\n      \"--label <name>\",\n      \"--prefer-tunnel <tailscale|ssh|manual|auto>\",\n      \"--repo-ref <ref>\"\n    ]\n  },\n  \"jsonSchemas\": {\n    \"error\": {\n      \"type\": \"object\",\n      \"required\": [\n        \"ok\",\n        \"error\"\n      ],\n      \"properties\": {\n        \"ok\": {\n          \"const\": false\n        },\n        \"error\": {\n          \"type\": \"object\",\n          \"required\": [\n            \"message\"\n          ],\n          \"properties\": {\n            \"message\": {\n              \"type\": \"string\"\n            },\n            \"code\": {\n              \"type\": \"string\"\n            }\n          },\n          \"additionalProperties\": false\n        }\n      },\n      \"additionalProperties\": false\n    },\n    \"future.repoListResult\": {\n      \"type\": \"object\",\n      \"description\": \"Reserved for #252 repo listing output.\"\n    },\n    \"future.paneCreateResult\": {\n      \"type\": \"object\",\n      \"description\": \"Reserved for #252 pane creation output.\"\n    }\n  }\n}")