Refactor public API around environments

docs/install.md

@@ -2,9 +2,8 @@
 
 ## Requirements
 
-- Linux host
+- Linux x86_64 host
 - Python 3.12+
-- Git LFS
 - `/dev/kvm`
 
 If you want outbound guest networking:
@@ -21,10 +20,16 @@ Run the MCP server directly from the package without a manual install:
 uvx --from pyro-mcp pyro mcp serve
 ```
 
-Run one command in a sandbox:
+Run one command in a curated environment:
 
 ```bash
-uvx --from pyro-mcp pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024 -- git --version
+uvx --from pyro-mcp pyro run debian:12 --vcpu-count 1 --mem-mib 1024 -- git --version
+```
+
+Inspect the official environment catalog:
+
+```bash
+uvx --from pyro-mcp pyro env list
 ```
 
 ## Installed CLI
@@ -32,6 +37,7 @@ uvx --from pyro-mcp pyro run --profile debian-git --vcpu-count 1 --mem-mib 1024
 ```bash
 uv tool install .
 pyro --version
+pyro env list
 pyro doctor
 ```
 

docs/integrations.md

@@ -29,7 +29,7 @@ Recommended surface:
 
 Canonical example:
 
-- [examples/openai_responses_vm_run.py](/home/thales/projects/personal/pyro/examples/openai_responses_vm_run.py)
+- [examples/openai_responses_vm_run.py](../examples/openai_responses_vm_run.py)
 
 ## MCP Clients
 
@@ -45,9 +45,9 @@ Recommended entrypoint:
 
 Starter config:
 
-- [examples/mcp_client_config.md](/home/thales/projects/personal/pyro/examples/mcp_client_config.md)
-- [examples/claude_desktop_mcp_config.json](/home/thales/projects/personal/pyro/examples/claude_desktop_mcp_config.json)
-- [examples/cursor_mcp_config.json](/home/thales/projects/personal/pyro/examples/cursor_mcp_config.json)
+- [examples/mcp_client_config.md](../examples/mcp_client_config.md)
+- [examples/claude_desktop_mcp_config.json](../examples/claude_desktop_mcp_config.json)
+- [examples/cursor_mcp_config.json](../examples/cursor_mcp_config.json)
 
 ## Direct Python SDK
 
@@ -63,8 +63,8 @@ Recommended default:
 
 Examples:
 
-- [examples/python_run.py](/home/thales/projects/personal/pyro/examples/python_run.py)
-- [examples/python_lifecycle.py](/home/thales/projects/personal/pyro/examples/python_lifecycle.py)
+- [examples/python_run.py](../examples/python_run.py)
+- [examples/python_lifecycle.py](../examples/python_lifecycle.py)
 
 ## Agent Framework Wrappers
 
@@ -87,7 +87,7 @@ Recommended pattern:
 
 Concrete example:
 
-- [examples/langchain_vm_run.py](/home/thales/projects/personal/pyro/examples/langchain_vm_run.py)
+- [examples/langchain_vm_run.py](../examples/langchain_vm_run.py)
 
 ## Selection Rule
 

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.

docs/troubleshooting.md

@@ -1,21 +1,25 @@
 # Troubleshooting
 
-## `pyro doctor` reports runtime checksum mismatch
+## `pyro env pull` or first-run install fails
 
 Cause:
-- the Git LFS pointer files are present, but the real runtime images have not been checked out
+
+- the environment cache directory is not writable
+- the configured environment source is unavailable
+- the environment download was interrupted
 
 Fix:
 
 ```bash
-git lfs pull
-git lfs checkout
-pyro doctor
+pyro env inspect debian:12
+pyro env prune
+pyro env pull debian:12
 ```
 
 ## `pyro run --network` fails before the guest starts
 
 Cause:
+
 - the host cannot create TAP devices or NAT rules
 
 Fix:
@@ -31,9 +35,22 @@ Then verify:
 - `/dev/net/tun`
 - host privilege for `sudo -n`
 
+## `pyro doctor` reports runtime issues
+
+Cause:
+
+- the embedded Firecracker runtime files are missing or corrupted
+
+Fix:
+
+- reinstall the package
+- verify `pyro doctor` reports `runtime_ok: true`
+- if you are working from a source checkout, ensure large runtime artifacts are present with `git lfs pull`
+
 ## 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:
@@ -47,18 +64,3 @@ 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/`.