Polish onboarding and CLI help

docs/first-run.md

@@ -0,0 +1,61 @@
+# First Run Transcript
+
+This is the intended evaluator path for a first successful run on a supported host.
+Copy the commands as-is. Paths and timing values will differ on your machine.
+
+## 1. Verify the host
+
+```bash
+$ uvx --from pyro-mcp pyro doctor
+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
+
+```bash
+$ uvx --from pyro-mcp pyro env list
+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
+Pulled: debian:12
+Version: 1.0.0
+Distribution: debian 12
+Installed: yes
+Cache dir: /home/you/.cache/pyro-mcp/environments
+Default packages: bash, coreutils, git
+Install dir: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0
+Install manifest: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/environment.json
+Kernel image: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/vmlinux
+Rootfs image: /home/you/.cache/pyro-mcp/environments/linux-x86_64/debian_12-1.0.0/rootfs.ext4
+OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0
+```
+
+## 4. Run one command in a guest
+
+```bash
+$ uvx --from pyro-mcp pyro run debian:12 -- git --version
+git version ...
+[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+```
+
+## 5. Optional next steps
+
+```bash
+$ uvx --from pyro-mcp pyro demo
+$ uvx --from pyro-mcp pyro mcp serve
+```
+
+If `pyro doctor` reports `Runtime: FAIL`, or if the `pyro run` summary does not show
+`execution_mode=guest_vsock`, stop and use [troubleshooting.md](troubleshooting.md).

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
 

docs/integrations.md

@@ -2,6 +2,9 @@
 
 These are the main ways to integrate `pyro-mcp` into an LLM application.
 
+Use this page after you have already validated the host and guest execution through the
+CLI path in [install.md](install.md) or [first-run.md](first-run.md).
+
 ## Recommended Default
 
 Use `vm_run` first.