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

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.