From 8bce1ed7d409de471eded2797c6acd6d002e0561 Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Fri, 6 Mar 2026 22:54:18 -0300
Subject: [PATCH] Align docs with real guest networking runtime

---
 AGENTS.md                 |  1 +
 README.md                 | 15 ++++++++++-----
 runtime_sources/README.md |  2 +-
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index cce2ee3..fc3e694 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,6 +20,7 @@ This repository ships `pyro-mcp`, an MCP-compatible package for ephemeral VM lif
 - Use `make network-demo` to validate deterministic VM lifecycle execution with guest networking enabled.
 - Use `make ollama-demo` to validate model-triggered lifecycle tool usage with guest networking enabled.
 - Use `make doctor` to inspect bundled runtime integrity and host prerequisites.
+- Network-enabled flows require host privilege for TAP/NAT setup; the current implementation uses `sudo -n` for `ip`, `nft`, and `iptables` when available.
 - If you need full log payloads from the Ollama demo, use `make ollama-demo OLLAMA_DEMO_FLAGS=-v`.
 
 ## Quality Gates
diff --git a/README.md b/README.md
index 9f8d7c3..80c1cbf 100644
--- a/README.md
+++ b/README.md
@@ -104,14 +104,21 @@ This prints bundled runtime paths, profile availability, checksum validation sta
 
 - 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:
+- Primary network-enabled entrypoints:
+
+```bash
+make network-demo
+make ollama-demo
+```
+
+- Network setup requires host privilege to manage TAP/NAT state.
+- The current implementation auto-uses `sudo -n` for `ip`, `nft`, and `iptables` commands when available.
+- Manual opt-in for other commands is still available with:
 
 ```bash
 PYRO_VM_ENABLE_NETWORK=1 make demo
 ```
 
-- Network setup requires host privilege to manage TAP/NAT state.
-- The current implementation auto-uses `sudo -n` for `ip`, `nft`, and `iptables` commands when available.
 - To validate real guest egress directly:
 
 ```bash
@@ -134,8 +141,6 @@ 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
diff --git a/runtime_sources/README.md b/runtime_sources/README.md
index 5f1ca68..866cfa3 100644
--- a/runtime_sources/README.md
+++ b/runtime_sources/README.md
@@ -5,7 +5,7 @@ Source-of-truth inputs for `make runtime-bundle`.
 Current state:
 - `build/runtime_sources/` contains the real materialized runtime inputs used to build the packaged bundle.
 - the checked-in tracked files under `runtime_sources/linux-x86_64/` are build recipes and lock metadata, not the materialized binaries/images.
-- `guest/pyro_guest_agent.py` is the guest agent artifact that should ultimately be installed into each real rootfs.
+- `guest/pyro_guest_agent.py` is the guest agent source artifact that is installed into each built rootfs.
 - real source materialization now writes into `build/runtime_sources/`, not back into the tracked placeholder files.
 
 Materialization workflow: