feat: expand runpane CLI and local Pane API surface

[parsakhaz]

Intent

Now that Pane has official npm, pnpm, and PyPI install clients, runpane is no longer just a packaging wrapper. It is becoming the first interface many users, developers, and agents will touch before they ever open the app. Expand the runpane CLI and local Pane API story so package-manager installs feel guided, transparent, and powerful instead of like a copy-pasted script silently doing work.

The product direction is: a first-time user should be able to install Pane from the package manager they already trust, run one memorable command, get clear feedback about what is happening, and optionally configure or operate their local Pane workspace from the terminal. Longer term, agents should be able to use a documented CLI/API surface to configure a user's Pane environment with user consent.

Product Motivation

Package-manager installs create a new trust and UX surface:

• Users understand npm, pnpm, pip, pipx, and uvx better than an opaque shell script.
• A CLI can explain what is happening before and during setup, which makes the install feel less scary and less like it is hanging.
• runpane setup gives Pane a memorable first-run command that works across ecosystems.
• One-liners such as npx --yes runpane@latest setup or pipx run runpane setup can still exist for quick starts, but the CLI should remain the source of feedback and explanation.
• The docs and website should point people toward this flow so future users consistently start with the same guided experience.

This is also a strategic surface. Pane currently has official Node and Python clients for installing/launching the app where competitors generally do not. That differentiator should not just be marketing copy; it should grow into a genuinely useful local control plane.

Desired User Experience

The ideal flow should feel like:

1. The user installs or runs runpane through their preferred package manager.
2. runpane setup guides them through install/reuse/update choices with clear status and explanations.
3. If Pane already exists locally, setup should reuse it when appropriate instead of doing unnecessary downloads.
4. If a daemon/workspace is available, the CLI should be able to connect to it and help configure useful settings from the terminal.
5. The user should be able to stay in Pane's terminal and make real-time configuration changes without needing to dig through UI first.

This does not need to become a custom auto-updater project. Package-manager users can update via npm/pnpm/PyPI tooling; the richer opportunity is setup, visibility, and workspace control.

Scope

Explore and define the next stage of the runpane CLI and local API story:

• Map what Pane can already do programmatically through the client daemon, IPC, settings services, workspace services, and remote setup surfaces.
• Identify which actions/settings are safe and useful to expose publicly.
• Define a user-facing CLI command surface for common local configuration, workspace, daemon, and status operations.
• Decide whether the first public surface should be CLI-only, HTTP/OpenAPI, or both.
• If an API is appropriate, define the first stable OpenAPI scope so humans and agents can inspect capabilities without relying on private internals.
• Make the agent use case explicit: an agent should be able to read a documented spec and configure Pane locally, but only within clear user-consent and safety boundaries.
• Keep install/update/package concerns separate from richer workspace-control commands so the package clients stay reliable and understandable.

Candidate Capabilities To Investigate

These are examples to investigate, not a final command list:

• runpane status: show installed app version, CLI package version, daemon status, workspace connection, and update guidance.
• runpane setup: guided first-run/install/reuse flow with strong progress feedback.
• runpane doctor: environment checks for app path, daemon reachability, platform support, permissions, and common install problems.
• runpane config get/set/list: terminal-friendly access to selected safe Pane settings.
• runpane workspace ...: inspect or switch relevant workspace/session state if the daemon model supports it safely.
• runpane daemon ...: start, stop, reconnect, or run remote setup where appropriate.
• runpane api spec: print or serve the local OpenAPI spec if we choose to expose one.
• Machine-readable output options such as --json for agents and scripts.

Agent / API Direction

A longer-term goal is for Pane to become easy for an agent to configure in a transparent, auditable way:

• The agent can discover available local capabilities from a CLI help surface or OpenAPI spec.
• The user can approve what the agent is allowed to do.
• The agent can configure the active Pane client, workspace, or daemon-backed workspace without relying on brittle UI automation.
• The same primitives remain usable by humans from the terminal.

This could become a strong differentiator: Pane would not only be installable from developer-native package managers, it would also expose a first-class local control plane for human and agent workflows.

Starting Points

These are non-exhaustive starting points. Treat them as a starting point and investigate further before implementation.

• Existing runpane npm/PyPI packages and their setup, install, update, daemon, and dry-run flows.
• Current package-manager docs and quick-start copy in the website/docs.
• The Pane client daemon and remote setup flow introduced during package-manager install work.
• Main-process IPC handlers and services that already own settings, workspace state, sessions, terminal state, remote daemon setup, and app lifecycle.
• Existing telemetry/download-source handling so future CLI/API usage can be understood without over-instrumenting.

Acceptance Criteria

• The current daemon/API capabilities relevant to local configuration are mapped and documented.
• The proposal identifies which capabilities are safe to expose publicly and which should remain internal.
• A proposed CLI command surface exists for first-run setup, status/doctor, and at least a first set of local configuration/workspace operations.
• The proposal includes example commands for npm, pnpm, pip/pipx/uvx users where relevant.
• A recommendation exists on whether to expose a local OpenAPI spec, and what its first stable scope should be.
• Safety and consent boundaries for agent-driven local configuration are explicit.
• The proposal distinguishes package-manager update behavior from richer workspace-control functionality.
• Follow-up implementation issues can be cut from the proposal without needing to recover this discussion thread.

Inputs Needed

• Product decision on which Pane settings/actions should be safe to expose through a public local CLI/API.
• Product decision on how explicit user consent should work for agent-driven configuration.
• Engineering decision on whether the first API surface should be HTTP/OpenAPI, CLI-only, or both.
• Engineering decision on how stable the daemon protocol needs to be before exposing it as a public contract.

Notes

The key product feel is that installing Pane should not feel like pasting a script and waiting in the dark. The CLI should narrate what matters, guide users through choices, and eventually become a capable local control surface. The future version should feel obvious in hindsight: if Pane can be installed from developer package managers, then of course it should also be configurable from the terminal and usable by agents through a documented local API.

[parsakhaz]

Added a focused follow-up for the first concrete orchestration use case: #252

The key refinement from the discussion is that the most valuable early public surface is not generic settings access. It is a stable runpane workflow that lets a human or local agent create visible panes in a selected repository, open built-in or custom terminal tool tabs, and seed each tab with an initial command/prompt.

Representative workflow: after creating several GitHub issues, an agent can run runpane to find/select the right repo, create one pane per issue, choose or ask which agent to use, open Codex/Claude/custom command tabs, and kick off something like the discussion skill against each issue. Normal Pane users should simply see the panes/tabs appear and update live.

This reinforces the product-level API direction here: publish curated commands/schemas such as repository listing, pane creation, tool tab creation, and initial command/prompt seeding, rather than exposing arbitrary internal daemon/IPC channel names as the public contract.

[parsakhaz]

Added a separate foundation issue for the shared-contract/codegen concern: #253

The goal is to avoid remembering to update npm, PyPI, docs, and tests independently as runpane grows. A contract-first approach, potentially OpenAPI/JSON Schema/TypeScript-schema driven, should let clients and docs derive from one stable product-level command/API contract.