Ship trust-first CLI and runtime defaults

docs/install.md

@@ -30,7 +30,7 @@ uvx --from pyro-mcp pyro env pull debian:12
 Run one command in a curated environment:
 
 ```bash
-uvx --from pyro-mcp pyro run debian:12 --vcpu-count 1 --mem-mib 1024 -- git --version
+uvx --from pyro-mcp pyro run debian:12 -- git --version
 ```
 
 Inspect the official environment catalog:
@@ -48,8 +48,13 @@ pyro env list
 pyro env pull debian:12
 pyro env inspect debian:12
 pyro doctor
+pyro run debian:12 -- git --version
 ```
 
+`pyro run` defaults to `1 vCPU / 1024 MiB`.
+If guest execution is unavailable, the command fails unless you explicitly pass
+`--allow-host-compat`.
+
 ## Contributor Clone
 
 ```bash

docs/public-contract.md

@@ -1,6 +1,6 @@
 # Public Contract
 
-This document defines the supported public interface for `pyro-mcp` `1.x`.
+This document defines the supported public interface for `pyro-mcp` `2.x`.
 
 ## Package Identity
 
@@ -31,12 +31,14 @@ Stable `pyro run` interface:
 - `--timeout-seconds`
 - `--ttl-seconds`
 - `--network`
+- `--allow-host-compat`
+- `--json`
 
 Behavioral guarantees:
 
-- `pyro run <environment> --vcpu-count <n> --mem-mib <mib> -- <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 run <environment> -- <command>` defaults to `1 vCPU / 1024 MiB`.
+- `pyro run` fails if guest boot or guest exec is unavailable unless `--allow-host-compat` is set.
+- `pyro run`, `pyro env list`, `pyro env pull`, `pyro env inspect`, `pyro env prune`, and `pyro doctor` are human-readable by default and return structured JSON with `--json`.
 - `pyro demo ollama` prints log lines plus a final summary line.
 
 ## Python SDK Contract
@@ -80,6 +82,11 @@ Stable public method names:
 - `reap_expired()`
 - `run_in_vm(...)`
 
+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(...)`.
+
 ## MCP Contract
 
 Primary tool:
@@ -98,6 +105,11 @@ Advanced lifecycle tools:
 - `vm_network_info`
 - `vm_reap_expired`
 
+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`.
+
 ## Versioning Rule
 
 - `pyro-mcp` uses SemVer.

docs/troubleshooting.md

@@ -20,6 +20,26 @@ 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 run` fails closed before the command executes
+
+Cause:
+
+- the bundled runtime cannot boot a guest
+- guest boot works but guest exec is unavailable
+- you are using a mock or shim runtime path that only supports host compatibility mode
+
+Fix:
+
+```bash
+pyro doctor
+```
+
+If you intentionally want host execution for a one-off compatibility run, rerun with:
+
+```bash
+pyro run --allow-host-compat debian:12 -- git --version
+```
+
 ## `pyro run --network` fails before the guest starts
 
 Cause: