Add runtime capability scaffolding and align docs

README.md

@@ -4,14 +4,14 @@
 
 ## v0.1.0 Capabilities
 
-- Split lifecycle tools for coding agents: `vm_list_profiles`, `vm_create`, `vm_start`, `vm_exec`, `vm_stop`, `vm_delete`, `vm_status`, `vm_reap_expired`.
+- Split lifecycle tools for coding agents: `vm_list_profiles`, `vm_create`, `vm_start`, `vm_exec`, `vm_stop`, `vm_delete`, `vm_status`, `vm_network_info`, `vm_reap_expired`.
 - Standard environment profiles:
 - `debian-base`: minimal Debian shell/core Unix tools.
 - `debian-git`: Debian base with Git preinstalled.
 - `debian-build`: Debian Git profile with common build tooling.
 - Explicit sizing contract for agents (`vcpu_count`, `mem_mib`) with guardrails.
 - Strict ephemerality for command execution (`vm_exec` auto-deletes VM on completion).
-- Ollama demo that asks an LLM to run `git --version` through lifecycle tools.
+- Ollama demo that asks an LLM to clone a small public Git repository through lifecycle tools.
 
 ## Runtime
 
@@ -22,6 +22,12 @@ The package includes a bundled Linux x86_64 runtime payload:
 
 No system Firecracker installation is required for basic usage.
 
+Current limitation:
+- The bundled runtime is currently shim-based.
+- `doctor` reports runtime capabilities, and current bundles report no real guest boot, no guest exec agent, and no guest networking.
+- Until a real guest-capable bundle is installed, `vm_exec` runs in `host_compat` mode rather than `guest_vsock`.
+- This means demo commands can exercise lifecycle/control-plane behavior, but they are not yet proof of command execution inside a real VM guest.
+
 Host requirements still apply:
 - Linux host
 - `/dev/kvm` available for full virtualization mode
@@ -44,7 +50,9 @@ make setup
 make demo
 ```
 
-The demo creates a VM, starts it, runs `git --version`, and returns structured output.
+The demo creates a VM, starts it, runs a command, and returns structured output.
+If the runtime reports `guest_vsock` plus networking, it uses an internet probe.
+Otherwise it falls back to a local compatibility command and the result will report `execution_mode=host_compat`.
 
 ## Runtime doctor
 
@@ -52,7 +60,21 @@ The demo creates a VM, starts it, runs `git --version`, and returns structured o
 make doctor
 ```
 
-This prints bundled runtime paths, profile availability, checksum validation status, and KVM host checks.
+This prints bundled runtime paths, profile availability, checksum validation status, runtime capability flags, KVM host checks, and host networking diagnostics.
+
+## Networking
+
+- Host-side network allocation and diagnostics are implemented.
+- The MCP server exposes `vm_network_info` for per-VM network metadata.
+- Host TAP/NAT setup is opt-in with:
+
+```bash
+PYRO_VM_ENABLE_NETWORK=1 make doctor
+```
+
+- Current limitation:
+  - network metadata and host preflight exist
+  - real in-guest outbound networking still depends on a non-shim runtime bundle with real guest boot and guest exec support
 
 ## Run Ollama lifecycle demo
 
@@ -64,6 +86,18 @@ make ollama-demo
 
 Defaults are configured in `Makefile`.
 The demo streams lifecycle progress logs and ends with a short text summary.
+The command it asks the model to run is a small public repository clone:
+
+```bash
+rm -rf hello-world && git clone --depth 1 https://github.com/octocat/Hello-World.git hello-world >/dev/null && git -C hello-world rev-parse --is-inside-work-tree
+```
+
+If the runtime is still shim-based, the summary will show `execution_mode=host_compat`.
+By default it omits log values; to include prompt content, tool args, and tool results use:
+
+```bash
+make ollama-demo OLLAMA_DEMO_FLAGS=-v
+```
 
 ## Run MCP server