Polish onboarding and CLI help

docs/install.md

@@ -1,59 +1,110 @@
 # Install
 
-## Requirements
+## Support Matrix
 
-- Linux x86_64 host
+Supported today:
+
+- Linux x86_64
 - Python 3.12+
 - `uv`
 - `/dev/kvm`
 
-If you want outbound guest networking:
+Optional for outbound guest networking:
 
 - `ip`
 - `nft` or `iptables`
 - privilege to create TAP devices and configure NAT
 
-## Fastest Start
+Not supported today:
 
-Run the MCP server directly from the package without a manual install:
+- 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
 ```
 
-Prefetch the default official environment:
+## Fastest Evaluation Path
+
+Use the package directly without a manual install:
+
+### 1. Check the host first
+
+```bash
+uvx --from pyro-mcp pyro doctor
+```
+
+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
+```
+
+If `Runtime: FAIL`, stop here and use [troubleshooting.md](troubleshooting.md).
+
+### 2. Inspect the catalog
+
+```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.
+```
+
+### 3. Pull the default environment
 
 ```bash
 uvx --from pyro-mcp pyro env pull debian:12
 ```
 
-Run one command in a curated environment:
+### 4. Run one command in a guest
 
 ```bash
 uvx --from pyro-mcp pyro run debian:12 -- git --version
 ```
 
-Inspect the official environment catalog:
+Expected success signals:
 
 ```bash
-uvx --from pyro-mcp pyro env list
+git version ...
+[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
 ```
 
+If guest execution is unavailable, the command fails unless you explicitly pass
+`--allow-host-compat`.
+
+For a fuller copy-pasteable transcript, see [first-run.md](first-run.md).
+
 ## Installed CLI
 
 ```bash
 uv tool install pyro-mcp
 pyro --version
+pyro doctor
 pyro env list
 pyro env pull debian:12
-pyro env inspect debian:12
-pyro doctor
 pyro run debian:12 -- git --version
 ```
 
-`pyro run` defaults to `1 vCPU / 1024 MiB`.
-If guest execution is unavailable, the command fails unless you explicitly pass
-`--allow-host-compat`.
+After the CLI path works, you can move on to:
+
+- MCP: `pyro mcp serve`
+- Python SDK: `from pyro_mcp import Pyro`
+- Demos: `pyro demo` or `pyro demo --network`
 
 ## Contributor Clone