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

README.md

@@ -9,6 +9,13 @@ It exposes the same runtime in two public forms:
 
 It also ships an MCP server so LLM clients can use the same VM runtime through tools.
 
+## Start Here
+
+- Install: [docs/install.md](/home/thales/projects/personal/pyro/docs/install.md)
+- Host requirements: [docs/host-requirements.md](/home/thales/projects/personal/pyro/docs/host-requirements.md)
+- Public contract: [docs/public-contract.md](/home/thales/projects/personal/pyro/docs/public-contract.md)
+- Troubleshooting: [docs/troubleshooting.md](/home/thales/projects/personal/pyro/docs/troubleshooting.md)
+
 ## Public UX
 
 Primary install/run path:
@@ -26,6 +33,12 @@ pyro mcp serve
 The public user-facing interface is `pyro` and `Pyro`.
 `Makefile` targets are contributor conveniences for this repository and are not the primary product UX.
 
+Check the installed CLI version:
+
+```bash
+pyro --version
+```
+
 ## Repository Storage
 
 This repository uses Git LFS for the packaged runtime images under
@@ -124,6 +137,13 @@ Verbose Ollama logs:
 pyro demo ollama -v
 ```
 
+## Integration Examples
+
+- Python one-shot SDK example: [examples/python_run.py](/home/thales/projects/personal/pyro/examples/python_run.py)
+- Python lifecycle example: [examples/python_lifecycle.py](/home/thales/projects/personal/pyro/examples/python_lifecycle.py)
+- MCP client config example: [examples/mcp_client_config.md](/home/thales/projects/personal/pyro/examples/mcp_client_config.md)
+- Agent-ready `vm_run` example: [examples/agent_vm_run.py](/home/thales/projects/personal/pyro/examples/agent_vm_run.py)
+
 ## Python SDK
 
 ```python
@@ -160,6 +180,9 @@ result = pyro.exec_vm(vm_id, command="git --version", timeout_seconds=30)
 print(result["stdout"])
 ```
 
+The recommended agent-facing default is still one-shot execution through `run_in_vm(...)` / `vm_run`.
+Use lifecycle methods only when the agent needs VM state to persist across multiple calls.
+
 ## MCP Tools
 
 Primary agent-facing tool:
@@ -212,6 +235,7 @@ For work inside this repository:
 make help
 make setup
 make check
+make dist-check
 ```
 
 Runtime build and validation helpers remain available through `make`, including: