Add adoption-focused examples, contract docs, and CLI polish

docs/host-requirements.md

@@ -0,0 +1,32 @@
+# Host Requirements
+
+`pyro-mcp` currently targets Linux x86_64 hosts.
+
+## Required
+
+- KVM available at `/dev/kvm`
+- support for Firecracker microVMs
+- sufficient disk for the bundled runtime images
+
+## Required For Guest Networking
+
+- `/dev/net/tun`
+- `ip`
+- `nft` or `iptables`
+- host IP forwarding enabled
+- privilege to create TAP devices and NAT rules
+
+The current implementation uses `sudo -n` for host networking commands when a networked run is requested.
+
+## Validate The Host
+
+```bash
+pyro doctor
+```
+
+Check these fields in the output:
+
+- `runtime_ok`
+- `kvm`
+- `networking.tun_available`
+- `networking.ip_forward_enabled`

docs/install.md

@@ -0,0 +1,46 @@
+# Install
+
+## Requirements
+
+- Linux host
+- Python 3.12+
+- Git LFS
+- `/dev/kvm`
+
+If you want outbound guest networking:
+
+- `ip`
+- `nft` or `iptables`
+- privilege to create TAP devices and configure NAT
+
+## Fastest Start
+
+Run the MCP server directly from the package without a manual install:
+
+```bash
+uvx --from pyro-mcp pyro mcp serve
+```
+
+Run one command in a sandbox:
+
+```bash
+uvx --from pyro-mcp pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 -- git --version
+```
+
+## Installed CLI
+
+```bash
+uv tool install .
+pyro --version
+pyro doctor
+```
+
+## Contributor Clone
+
+```bash
+git lfs install
+git clone <repo>
+cd pyro
+git lfs pull
+make setup
+```

docs/public-contract.md

@@ -0,0 +1,76 @@
+# Public Contract
+
+This document defines the supported public interface for `pyro-mcp`.
+
+## Package Identity
+
+- Distribution name: `pyro-mcp`
+- Public executable: `pyro`
+- Public Python import: `from pyro_mcp import Pyro`
+
+## CLI Contract
+
+Top-level commands:
+
+- `pyro mcp serve`
+- `pyro run`
+- `pyro doctor`
+- `pyro demo`
+- `pyro demo ollama`
+
+Stable `pyro run` flags:
+
+- `--profile`
+- `--vcpu-count`
+- `--mem-mib`
+- `--timeout-seconds`
+- `--ttl-seconds`
+- `--network`
+
+Behavioral guarantees:
+
+- `pyro run -- <command>` returns structured JSON.
+- `pyro doctor` returns structured JSON diagnostics.
+- `pyro demo ollama` prints log lines plus a final summary line.
+
+## Python SDK Contract
+
+Primary facade:
+
+- `Pyro`
+
+Supported public methods:
+
+- `create_server()`
+- `list_profiles()`
+- `create_vm(...)`
+- `start_vm(vm_id)`
+- `exec_vm(vm_id, *, command, timeout_seconds=30)`
+- `stop_vm(vm_id)`
+- `delete_vm(vm_id)`
+- `status_vm(vm_id)`
+- `network_info_vm(vm_id)`
+- `reap_expired()`
+- `run_in_vm(...)`
+
+## MCP Contract
+
+Primary tool:
+
+- `vm_run`
+
+Advanced lifecycle tools:
+
+- `vm_list_profiles`
+- `vm_create`
+- `vm_start`
+- `vm_exec`
+- `vm_stop`
+- `vm_delete`
+- `vm_status`
+- `vm_network_info`
+- `vm_reap_expired`
+
+## Compatibility Rule
+
+Changes to any command name, public flag, public method name, or MCP tool name are breaking changes and should be treated as a deliberate contract version change.

docs/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting
+
+## `pyro doctor` reports runtime checksum mismatch
+
+Cause:
+- the Git LFS pointer files are present, but the real runtime images have not been checked out
+
+Fix:
+
+```bash
+git lfs pull
+git lfs checkout
+pyro doctor
+```
+
+## `pyro run --network` fails before the guest starts
+
+Cause:
+- the host cannot create TAP devices or NAT rules
+
+Fix:
+
+```bash
+pyro doctor
+```
+
+Then verify:
+
+- `ip`
+- `nft` or `iptables`
+- `/dev/net/tun`
+- host privilege for `sudo -n`
+
+## Ollama demo exits with tool-call failures
+
+Cause:
+- the model produced an invalid tool call or your Ollama model is not reliable enough for tool use
+
+Fix:
+
+```bash
+pyro demo ollama -v
+```
+
+Inspect:
+
+- model output
+- requested tool calls
+- tool results
+
+## Repository clone is still huge after the LFS migration
+
+Cause:
+- old refs are still present locally
+- `build/` or `.venv/` duplicates are consuming disk
+
+Fix:
+
+```bash
+rm -rf build
+git lfs prune
+```
+
+If needed, recreate `.venv/`.