Harden default environment pull behavior

Fix the default one-shot install path so empty bundled profile directories no longer win over OCI-backed environment pulls or leave broken cached symlinks behind.

Treat cached installs as valid only when the manifest and boot artifacts are all present, repair invalid installs on the next pull, and add human-mode phase markers for env pull and run without changing JSON output.

Align the Python lifecycle example and public docs with the current exec_vm/vm_exec auto-clean semantics, and validate the slice with focused pytest coverage, make check, make dist-check, and a real default-path pull/inspect/run smoke.

docs/first-run.md

@@ -36,6 +36,8 @@ access to `registry-1.docker.io`, and needs local cache space for the guest imag
 
 ```bash
 $ uvx --from pyro-mcp pyro env pull debian:12
+[pull] phase=install environment=debian:12
+[pull] phase=ready environment=debian:12
 Pulled: debian:12
 Version: 1.0.0
 Distribution: debian 12
@@ -53,6 +55,9 @@ OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0
 
 ```bash
 $ uvx --from pyro-mcp pyro run debian:12 -- git --version
+[run] phase=create environment=debian:12
+[run] phase=start vm_id=...
+[run] phase=execute vm_id=...
 [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
 git version ...
 ```

docs/install.md

@@ -99,6 +99,15 @@ The first pull downloads an OCI environment from public Docker Hub, requires out
 access to `registry-1.docker.io`, and needs local cache space for the guest image. See
 [host-requirements.md](host-requirements.md) for the full host requirements.
 
+Expected success signals:
+
+```bash
+[pull] phase=install environment=debian:12
+[pull] phase=ready environment=debian:12
+Pulled: debian:12
+...
+```
+
 ### 4. Run one command in a guest
 
 ```bash
@@ -108,6 +117,9 @@ uvx --from pyro-mcp pyro run debian:12 -- git --version
 Expected success signals:
 
 ```bash
+[run] phase=create environment=debian:12
+[run] phase=start vm_id=...
+[run] phase=execute vm_id=...
 [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
 git version ...
 ```

docs/integrations.md

@@ -64,6 +64,12 @@ Recommended default:
 
 - `Pyro.run_in_vm(...)`
 
+Lifecycle note:
+
+- `Pyro.exec_vm(...)` runs one command and auto-cleans the VM afterward
+- use `create_vm(...)` + `start_vm(...)` only when you need pre-exec inspection or status before
+  that final exec
+
 Examples:
 
 - [examples/python_run.py](../examples/python_run.py)

docs/public-contract.md

@@ -86,6 +86,7 @@ Behavioral defaults:
 
 - `Pyro.create_vm(...)` and `Pyro.run_in_vm(...)` default to `vcpu_count=1` and `mem_mib=1024`.
 - `allow_host_compat` defaults to `False` on `create_vm(...)` and `run_in_vm(...)`.
+- `Pyro.exec_vm(...)` runs one command and auto-cleans that VM after the exec completes.
 
 ## MCP Contract
 
@@ -109,6 +110,7 @@ Behavioral defaults:
 
 - `vm_run` and `vm_create` default to `vcpu_count=1` and `mem_mib=1024`.
 - `vm_run` and `vm_create` expose `allow_host_compat`, which defaults to `false`.
+- `vm_exec` runs one command and auto-cleans that VM after the exec completes.
 
 ## Versioning Rule
 

docs/troubleshooting.md

@@ -20,6 +20,9 @@ pyro env pull debian:12
 If you are validating a freshly published official environment, also verify that the corresponding
 Docker Hub repository is public.
 
+`PYRO_RUNTIME_BUNDLE_DIR` is a contributor override for validating a locally built runtime bundle.
+End-user `pyro env pull` should work without setting it.
+
 ## `pyro run` fails closed before the command executes
 
 Cause: