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

src/pyro_mcp/__init__.py

@@ -1,7 +1,11 @@
 """Public package surface for pyro_mcp."""
 
+from importlib.metadata import version
+
 from pyro_mcp.api import Pyro
 from pyro_mcp.server import create_server
 from pyro_mcp.vm_manager import VmManager
 
-__all__ = ["Pyro", "VmManager", "create_server"]
+__version__ = version("pyro-mcp")
+
+__all__ = ["Pyro", "VmManager", "__version__", "create_server"]

src/pyro_mcp/cli.py

@@ -6,6 +6,7 @@ import argparse
 import json
 from typing import Any
 
+from pyro_mcp import __version__
 from pyro_mcp.api import Pyro
 from pyro_mcp.demo import run_demo
 from pyro_mcp.ollama_demo import DEFAULT_OLLAMA_BASE_URL, DEFAULT_OLLAMA_MODEL, run_ollama_tool_demo
@@ -18,6 +19,7 @@ def _print_json(payload: dict[str, Any]) -> None:
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="pyro CLI for ephemeral Firecracker VMs.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     mcp_parser = subparsers.add_parser("mcp", help="Run the MCP server.")

src/pyro_mcp/contract.py

@@ -0,0 +1,41 @@
+"""Public contract constants for the CLI, SDK, and MCP server."""
+
+from __future__ import annotations
+
+PUBLIC_CLI_COMMANDS = ("mcp", "run", "doctor", "demo")
+PUBLIC_CLI_DEMO_SUBCOMMANDS = ("ollama",)
+PUBLIC_CLI_RUN_FLAGS = (
+    "--profile",
+    "--vcpu-count",
+    "--mem-mib",
+    "--timeout-seconds",
+    "--ttl-seconds",
+    "--network",
+)
+
+PUBLIC_SDK_METHODS = (
+    "create_server",
+    "create_vm",
+    "delete_vm",
+    "exec_vm",
+    "list_profiles",
+    "network_info_vm",
+    "reap_expired",
+    "run_in_vm",
+    "start_vm",
+    "status_vm",
+    "stop_vm",
+)
+
+PUBLIC_MCP_TOOLS = (
+    "vm_run",
+    "vm_list_profiles",
+    "vm_create",
+    "vm_start",
+    "vm_exec",
+    "vm_stop",
+    "vm_delete",
+    "vm_status",
+    "vm_network_info",
+    "vm_reap_expired",
+)