Add guided runpane setup flow

README.md

@@ -25,29 +25,33 @@
 
 **Quick install (recommended)**
 
-<sub>Package manager</sub><br />
-<pre><code>npx --yes runpane@latest install client</code></pre>
+<pre><code>npx --yes runpane@latest</code></pre>
+
+<sub>Opens a guided setup for desktop install, remote host setup, updates, and diagnostics.</sub>
+
+<br />
+<br />
+
+<details>
+<summary><sub>Other install methods</sub></summary>
+<br />
 
 <sub>pnpm</sub><br />
-<pre><code>pnpm dlx runpane@latest install client</code></pre>
+<pre><code>pnpm dlx runpane@latest</code></pre>
 
 <sub>Python tools</sub><br />
-<pre><code>pipx run runpane install client</code></pre>
+<pre><code>pipx run runpane</code></pre>
 
-<sub>or use the shell installers</sub><br />
+<sub>Persistent npm install</sub><br />
+<pre><code>npm i -g runpane
+runpane setup</code></pre>
 
-<sub>Mac / Linux</sub><br />
+<sub>Mac / Linux shell installer</sub><br />
 <pre><code>curl -fsSL https://runpane.com/install.sh | sh</code></pre>
 
-<sub>Windows (PowerShell)</sub><br />
+<sub>Windows PowerShell installer</sub><br />
 <pre><code>irm https://runpane.com/install.ps1 | iex</code></pre>
 
-<sub><em>Bypasses the macOS Gatekeeper / Windows SmartScreen prompts on direct downloads.</em></sub>
-
-<br />
-
-<sub>or download the installer directly</sub>
-
 <a href="https://runpane.com/api/download?platform=mac&source=readme">
   <img src="https://img.shields.io/badge/Download_for_macOS-000?style=for-the-badge&logo=apple&logoColor=white" height="40" alt="Download for macOS">
 </a>
@@ -58,6 +62,8 @@
   <img src="https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" height="40" alt="Download for Linux">
 </a>
 
+</details>
+
 <br />
 <br />
 
@@ -189,19 +195,40 @@ Other tools build custom chat UIs that only work with agents they've explicitly
 
 ### Quick Install
 
-**Package manager:**
+Run the guided setup:
+
+```bash
+npx --yes runpane@latest
+```
+
+The wizard can install Pane on this machine, configure this machine as a remote
+host, update Pane, or run diagnostics.
+
+### Advanced Install Methods
+
+Explicit desktop install:
+
 ```bash
 npx --yes runpane@latest install client
 pnpm dlx runpane@latest install client
 pipx run runpane install client
 ```
 
-**Mac / Linux:**
+Persistent npm install:
+
+```bash
+npm i -g runpane
+runpane setup
+```
+
+Mac / Linux shell installer:
+
 ```bash
 curl -fsSL https://runpane.com/install.sh | sh
 ```
 
-**Windows (PowerShell):**
+Windows PowerShell installer:
+
 ```powershell
 irm https://runpane.com/install.ps1 | iex
 ```

docs/RUNPANE_CLI_CONTRACT.md

@@ -15,9 +15,9 @@ Treat this file as the source of truth for both wrapper packages:
   rule change must be reflected here.
 - The npm and PyPI wrappers must expose the same command behavior unless this
   contract explicitly documents a package-manager-specific difference.
-- Root `README.md` should show the recommended user commands only. Package
-  READMEs may include package-specific runners such as `yarn dlx`, `bunx`,
-  `pipx`, or `uvx`.
+- 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.
 - 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.
@@ -37,13 +37,29 @@ out of the wrapper unless a compatibility test covers the new dependency.
 
 ## Package Manager Entrypoints
 
+Recommended guided quick starts:
+
+```bash
+npx --yes runpane@latest
+npm i -g runpane && runpane setup
+pipx run runpane
+python -m pip install runpane && python -m runpane setup
+```
+
 Canonical npm and Node commands:
 
 ```bash
+npx --yes runpane@latest
+npx --yes runpane@latest setup
 npx --yes runpane@latest install client
 npx --yes runpane@latest install daemon --label "My Server"
-npm i -g runpane && runpane install daemon --label "My Server"
+pnpm dlx runpane@latest
 pnpm dlx runpane@latest install daemon --label "My Server"
+npm i -g runpane && runpane
+npm i -g runpane && runpane setup
+npm i -g runpane && runpane install daemon --label "My Server"
+pnpm add -g runpane && runpane
+pnpm add -g runpane && runpane setup
 pnpm add -g runpane && runpane install daemon --label "My Server"
 yarn dlx runpane@latest install daemon --label "My Server"
 bunx runpane@latest install daemon --label "My Server"
@@ -52,10 +68,19 @@ bunx runpane@latest install daemon --label "My Server"
 Canonical Python commands:
 
 ```bash
+pipx run runpane
+pipx run runpane setup
 python -m pip install runpane
+runpane
+runpane setup
+python -m runpane setup
 runpane install daemon --label "My Server"
 pipx install runpane
+runpane
+runpane setup
 pipx run runpane install daemon --label "My Server"
+uvx runpane@latest
+uvx runpane@latest setup
 uvx runpane@latest install daemon --label "My Server"
 python -m runpane install daemon --label "My Server"
 ```
@@ -67,6 +92,8 @@ install path.
 ## Commands
 
 ```bash
+runpane
+runpane setup
 runpane install
 runpane install client
 runpane install daemon
@@ -77,6 +104,11 @@ runpane help
 runpane <command> --help
 ```
 
+When stdin and stdout are TTYs, `runpane` with no arguments and `runpane setup`
+open an interactive wizard for desktop install, remote host setup, update, and
+diagnostics. In non-interactive shells or CI, both forms must print help and
+exit successfully instead of waiting for input.
+
 `runpane install` is an alias for `runpane install client`.
 
 `runpane install client` downloads the selected Pane desktop artifact and

packages/runpane-py/README.md

@@ -1,38 +1,66 @@
 # runpane
 
-Thin PyPI installer and remote setup CLI for Pane.
+Install or configure Pane from PyPI.
 
 The package does not include the Pane desktop runtime. It downloads the correct
 Pane release artifact only when you run `runpane install` or `runpane update`.
 
-## Usage
+## Quick Start
 
-One-shot execution:
+Run the guided setup:
 
 ```bash
-pipx run runpane install daemon --label "My Server"
-uvx runpane@latest install daemon --label "My Server"
+pipx run runpane
 ```
 
 Persistent install:
 
 ```bash
 python -m pip install runpane
-runpane install daemon --label "My Server"
+python -m runpane setup
+```
 
-pipx install runpane
-runpane install daemon --label "My Server"
+The wizard can install Pane on this machine, configure this machine as a remote
+host, update Pane, or run diagnostics.
+
+## Advanced
+
+### Explicit Commands
+
+```bash
+pipx run runpane setup
+pipx run runpane install client
+pipx run runpane install daemon --label "My Server"
+pipx run runpane update
+pipx run runpane doctor
 ```
 
-Module entrypoint:
+`runpane install daemon` installs Pane and then invokes the installed executable
+with `--remote-setup`, preserving the `pane-remote://...` connection-code output.
+
+### Python Runners
+
+One-shot execution:
 
 ```bash
-python -m runpane install daemon --label "My Server"
+uvx runpane@latest
 ```
 
-## Commands
+Persistent install:
 
 ```bash
+python -m pip install runpane
+python -m runpane setup
+
+pipx install runpane
+runpane setup
+```
+
+### Commands
+
+```bash
+runpane
+runpane setup
 runpane install
 runpane install client
 runpane install daemon
@@ -42,8 +70,24 @@ runpane doctor
 runpane --help
 ```
 
-`runpane install daemon` installs Pane and then invokes the installed executable
-with `--remote-setup`, preserving the `pane-remote://...` connection-code output.
+### Common Options
+
+```bash
+--version <latest|vX.Y.Z>
+--format <auto|appimage|deb|dmg|zip|exe>
+--download-dir <path>
+--pane-path <path>
+--dry-run
+--verbose
+```
+
+Daemon setup also forwards Pane remote-host options:
+
+```bash
+--label <name>
+--prefer-tunnel <tailscale|ssh|manual|auto>
+--print-only
+```
 
 ## Attribution