Refactor public API around environments

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/`.