Polish onboarding and CLI help

README.md

@@ -11,26 +11,110 @@ It exposes the same runtime in three public forms:
 ## Start Here
 
 - Install: [docs/install.md](docs/install.md)
+- First run transcript: [docs/first-run.md](docs/first-run.md)
 - Host requirements: [docs/host-requirements.md](docs/host-requirements.md)
 - Integration targets: [docs/integrations.md](docs/integrations.md)
 - Public contract: [docs/public-contract.md](docs/public-contract.md)
 - Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
 
-## Public UX
+## Supported Hosts
 
-Primary install/run path:
+Supported today:
+
+- Linux x86_64
+- Python 3.12+
+- `uv`
+- `/dev/kvm`
+
+Optional for outbound guest networking:
+
+- `ip`
+- `nft` or `iptables`
+- privilege to create TAP devices and configure NAT
+
+Not supported today:
+
+- macOS
+- Windows
+- Linux hosts without working KVM at `/dev/kvm`
+
+If you do not already have `uv`, install it first:
 
 ```bash
-uvx --from pyro-mcp pyro mcp serve
+python -m pip install uv
 ```
 
-Installed package path:
+## 5-Minute Evaluation
+
+Use the package directly without a manual install:
+
+### 1. Check the host
 
 ```bash
-pyro mcp serve
+uvx --from pyro-mcp pyro doctor
 ```
 
-The public user-facing interface is `pyro` and `Pyro`.
+Expected success signals:
+
+```bash
+Platform: linux-x86_64
+Runtime: PASS
+KVM: exists=yes readable=yes writable=yes
+Environment cache: /home/you/.cache/pyro-mcp/environments
+Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
+Networking: tun=yes ip_forward=yes
+```
+
+### 2. Inspect the catalog and pull the default environment
+
+```bash
+uvx --from pyro-mcp pyro env list
+```
+
+Expected output:
+
+```bash
+Catalog version: 2.0.0
+debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
+debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
+debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
+```
+
+```bash
+uvx --from pyro-mcp pyro env pull debian:12
+```
+
+### 3. Run one command in a guest
+
+```bash
+uvx --from pyro-mcp pyro run debian:12 -- git --version
+```
+
+Expected success signals:
+
+```bash
+git version ...
+[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+```
+
+### 4. Optional demos
+
+```bash
+uvx --from pyro-mcp pyro demo
+uvx --from pyro-mcp pyro demo --network
+```
+
+If you prefer a fuller copy-pasteable transcript, see [docs/first-run.md](docs/first-run.md).
+
+## Public Interfaces
+
+The public user-facing interface is `pyro` and `Pyro`. After the CLI validation path works, you can choose one of three surfaces:
+
+- `pyro` for direct CLI usage
+- `from pyro_mcp import Pyro` for Python orchestration
+- `pyro mcp serve` for MCP clients
+
 `Makefile` targets are contributor conveniences for this repository and are not the primary product UX.
 
 ## Official Environments
@@ -86,6 +170,12 @@ pyro doctor --json
 It fails closed when guest boot or guest exec is unavailable.
 Use `--allow-host-compat` only if you explicitly want host execution.
 
+Run the MCP server after the CLI path above works:
+
+```bash
+pyro mcp serve
+```
+
 Run the deterministic demo:
 
 ```bash