Bundle firecracker runtime and switch ollama demo to live logs

README.md

@@ -1,19 +1,36 @@
 # pyro-mcp
 
-`pyro-mcp` is a minimal Python library that exposes an MCP-compatible server with one static tool.
+`pyro-mcp` is an MCP-compatible tool package for running ephemeral development environments with a VM lifecycle API.
 
-## v0.0.1 Features
+## v0.1.0 Capabilities
 
-- Official Python MCP SDK integration.
-- Public server factory: `pyro_mcp.create_server()`.
-- One static MCP tool: `hello_static`.
-- Runnable demonstration script.
-- Project automation via `Makefile`, `pre-commit`, `ruff`, `mypy`, and `pytest`.
+- Split lifecycle tools for coding agents: `vm_list_profiles`, `vm_create`, `vm_start`, `vm_exec`, `vm_stop`, `vm_delete`, `vm_status`, `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.
+
+## Runtime
+
+The package includes a bundled Linux x86_64 runtime payload:
+- Firecracker binary
+- Jailer binary
+- Profile artifacts for `debian-base`, `debian-git`, and `debian-build`
+
+No system Firecracker installation is required for basic usage.
+
+Host requirements still apply:
+- Linux host
+- `/dev/kvm` available for full virtualization mode
 
 ## Requirements
 
 - Python 3.12+
-- `uv` installed
+- `uv`
+- Optional for Ollama demo: local Ollama server and `llama:3.2-3b` model.
 
 ## Setup
 
@@ -21,70 +38,51 @@
 make setup
 ```
 
-This installs runtime and development dependencies into `.venv`.
-
-## Run the demo
+## Run deterministic lifecycle demo
 
 ```bash
 make demo
 ```
 
-Expected output:
+The demo creates a VM, starts it, runs `git --version`, and returns structured output.
 
-```json
-{
-  "message": "hello from pyro_mcp",
-  "status": "ok",
-  "version": "0.0.1"
-}
+## Runtime doctor
+
+```bash
+make doctor
 ```
 
-## Run the Ollama tool-calling demo
+This prints bundled runtime paths, profile availability, checksum validation status, and KVM host checks.
 
-Start Ollama and ensure the model is available (defaults to `llama:3.2-3b`):
+## Run Ollama lifecycle demo
 
 ```bash
 ollama serve
 ollama pull llama:3.2-3b
-```
-
-Then run:
-
-```bash
 make ollama-demo
 ```
 
-You can also run `make ollama demo` to execute both demos in one command.
-The Make target defaults to model `llama:3.2-3b` and can be overridden:
+Defaults are configured in `Makefile`.
+The demo streams lifecycle progress logs and ends with a short text summary.
 
-```bash
-make ollama-demo OLLAMA_MODEL=llama3.2:3b
-```
-
-## Run checks
-
-```bash
-make check
-```
-
-`make check` runs:
-
-- `ruff` lint checks
-- `mypy` type checks
-- `pytest` (with coverage threshold configured in `pyproject.toml`)
-
-## Run MCP server (stdio transport)
+## Run MCP server
 
 ```bash
 make run-server
 ```
 
-## Pre-commit
+## Quality checks
 
-Install hooks:
+```bash
+make check
+```
+
+Includes `ruff`, `mypy`, and `pytest` with coverage threshold.
+
+## Pre-commit
 
 ```bash
 make install-hooks
 ```
 
-Hooks run `ruff`, `mypy`, and `pytest` on each commit.
+Hooks execute the same lint/type/test gates.