Refactor public API around environments

docs/public-contract.md

@@ -1,6 +1,6 @@
 # Public Contract
 
-This document defines the supported public interface for `pyro-mcp`.
+This document defines the supported public interface for `pyro-mcp` `1.x`.
 
 ## Package Identity
 
@@ -12,15 +12,19 @@ This document defines the supported public interface for `pyro-mcp`.
 
 Top-level commands:
 
+- `pyro env list`
+- `pyro env pull`
+- `pyro env inspect`
+- `pyro env prune`
 - `pyro mcp serve`
 - `pyro run`
 - `pyro doctor`
 - `pyro demo`
 - `pyro demo ollama`
 
-Stable `pyro run` flags:
+Stable `pyro run` interface:
 
-- `--profile`
+- positional environment name
 - `--vcpu-count`
 - `--mem-mib`
 - `--timeout-seconds`
@@ -29,7 +33,8 @@ Stable `pyro run` flags:
 
 Behavioral guarantees:
 
-- `pyro run -- <command>` returns structured JSON.
+- `pyro run <environment> -- <command>` returns structured JSON.
+- `pyro env list`, `pyro env pull`, `pyro env inspect`, and `pyro env prune` return structured JSON.
 - `pyro doctor` returns structured JSON diagnostics.
 - `pyro demo ollama` prints log lines plus a final summary line.
 
@@ -42,7 +47,10 @@ Primary facade:
 Supported public methods:
 
 - `create_server()`
-- `list_profiles()`
+- `list_environments()`
+- `pull_environment(environment)`
+- `inspect_environment(environment)`
+- `prune_environments()`
 - `create_vm(...)`
 - `start_vm(vm_id)`
 - `exec_vm(vm_id, *, command, timeout_seconds=30)`
@@ -61,7 +69,7 @@ Primary tool:
 
 Advanced lifecycle tools:
 
-- `vm_list_profiles`
+- `vm_list_environments`
 - `vm_create`
 - `vm_start`
 - `vm_exec`
@@ -71,6 +79,8 @@ Advanced lifecycle tools:
 - `vm_network_info`
 - `vm_reap_expired`
 
-## Compatibility Rule
+## Versioning 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.
+- `pyro-mcp` uses SemVer.
+- Environment names are stable identifiers in the shipped catalog.
+- Changing a public command name, public flag, public method name, public MCP tool name, or required request field is a breaking change.