Ship trust-first CLI and runtime defaults

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: