Add adoption-focused examples, contract docs, and CLI polish

docs/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting
+
+## `pyro doctor` reports runtime checksum mismatch
+
+Cause:
+- the Git LFS pointer files are present, but the real runtime images have not been checked out
+
+Fix:
+
+```bash
+git lfs pull
+git lfs checkout
+pyro doctor
+```
+
+## `pyro run --network` fails before the guest starts
+
+Cause:
+- the host cannot create TAP devices or NAT rules
+
+Fix:
+
+```bash
+pyro doctor
+```
+
+Then verify:
+
+- `ip`
+- `nft` or `iptables`
+- `/dev/net/tun`
+- host privilege for `sudo -n`
+
+## 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:
+
+```bash
+pyro demo ollama -v
+```
+
+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/`.