Add terminal walkthrough assets

README.md

@@ -2,6 +2,10 @@
 
 `pyro-mcp` runs commands inside ephemeral Firecracker microVMs using curated Linux environments such as `debian:12`.
 
+[![PyPI version](https://img.shields.io/pypi/v/pyro-mcp.svg)](https://pypi.org/project/pyro-mcp/)
+
+This is for coding agents, MCP clients, and developers who want isolated command execution in ephemeral microVMs.
+
 It exposes the same runtime in three public forms:
 
 - the `pyro` CLI
@@ -12,6 +16,7 @@ It exposes the same runtime in three public forms:
 
 - Install: [docs/install.md](docs/install.md)
 - First run transcript: [docs/first-run.md](docs/first-run.md)
+- Terminal walkthrough GIF: [docs/assets/first-run.gif](docs/assets/first-run.gif)
 - PyPI package: [pypi.org/project/pyro-mcp](https://pypi.org/project/pyro-mcp/)
 - Host requirements: [docs/host-requirements.md](docs/host-requirements.md)
 - Integration targets: [docs/integrations.md](docs/integrations.md)
@@ -63,6 +68,8 @@ uv run pyro doctor
 
 Use the package directly without a manual install:
 
+If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`.
+
 ### 1. Check the host
 
 ```bash
@@ -127,7 +134,29 @@ uvx --from pyro-mcp pyro demo
 uvx --from pyro-mcp pyro demo --network
 ```
 
+`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
+
+Example output:
+
+```json
+{
+  "cleanup": {
+    "deleted": true,
+    "reason": "post_exec_cleanup",
+    "vm_id": "..."
+  },
+  "command": "git --version",
+  "environment": "debian:12",
+  "execution_mode": "guest_vsock",
+  "exit_code": 0,
+  "stdout": "git version ...\n"
+}
+```
+
+When you are done evaluating and want to remove stale cached environments, run `pyro env prune`.
+
 If you prefer a fuller copy-pasteable transcript, see [docs/first-run.md](docs/first-run.md).
+The walkthrough GIF above was rendered from [docs/assets/first-run.tape](docs/assets/first-run.tape) using [scripts/render_tape.sh](scripts/render_tape.sh).
 
 ## Public Interfaces
 

docs/assets/first-run.tape

@@ -0,0 +1,50 @@
+Output docs/assets/first-run.gif
+
+Require uv
+
+Set Shell "zsh"
+Set FontSize 18
+Set Width 1200
+Set Height 820
+Set Theme "Dracula"
+Set TypingSpeed 35ms
+Set Padding 24
+Set WindowBar Colorful
+
+Hide
+Type "cd /home/thales/projects/personal/pyro"
+Enter
+Type "export UV_CACHE_DIR=.uv-cache"
+Enter
+Show
+
+Type "printf '\\n# Check host support from the repo checkout\\n'"
+Enter
+Sleep 800ms
+Type "uv run pyro doctor"
+Enter
+Sleep 2200ms
+
+Type "printf '\\n# Inspect and pull the default environment\\n'"
+Enter
+Sleep 800ms
+Type "uv run pyro env list"
+Enter
+Sleep 1800ms
+Type "uv run pyro env pull debian:12"
+Enter
+Sleep 1800ms
+
+Type "printf '\\n# Run one command in an isolated guest\\n'"
+Enter
+Sleep 800ms
+Type "uv run pyro run debian:12 -- git --version"
+Enter
+Sleep 2200ms
+
+Type "printf '\\n# Prove the one-shot VM lifecycle demo\\n'"
+Enter
+Sleep 800ms
+Type "uv run pyro demo"
+Enter
+Sleep 2600ms

docs/first-run.md

@@ -67,5 +67,26 @@ $ uvx --from pyro-mcp pyro demo
 $ uvx --from pyro-mcp pyro mcp serve
 ```
 
+`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
+
+Example output:
+
+```json
+{
+  "cleanup": {
+    "deleted": true,
+    "reason": "post_exec_cleanup",
+    "vm_id": "..."
+  },
+  "command": "git --version",
+  "environment": "debian:12",
+  "execution_mode": "guest_vsock",
+  "exit_code": 0,
+  "stdout": "git version ...\n"
+}
+```
+
+When you are done evaluating and want to remove stale cached environments, run `pyro env prune`.
+
 If `pyro doctor` reports `Runtime: FAIL`, or if the `pyro run` summary does not show
 `execution_mode=guest_vsock`, stop and use [troubleshooting.md](troubleshooting.md).

docs/install.md

@@ -37,6 +37,8 @@ Use these command forms consistently:
 
 Use the package directly without a manual install:
 
+If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`.
+
 ### 1. Check the host first
 
 ```bash
@@ -101,7 +103,33 @@ deterministic structured result.
 If guest execution is unavailable, the command fails unless you explicitly pass
 `--allow-host-compat`.
 
+## 5. Optional demo proof point
+
+```bash
+uvx --from pyro-mcp pyro demo
+```
+
+`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
+
+Example output:
+
+```json
+{
+  "cleanup": {
+    "deleted": true,
+    "reason": "post_exec_cleanup",
+    "vm_id": "..."
+  },
+  "command": "git --version",
+  "environment": "debian:12",
+  "execution_mode": "guest_vsock",
+  "exit_code": 0,
+  "stdout": "git version ...\n"
+}
+```
+
 For a fuller copy-pasteable transcript, see [first-run.md](first-run.md).
+When you are done evaluating and want to remove stale cached environments, run `pyro env prune`.
 
 ## Installed CLI
 

scripts/render_tape.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
+    printf 'Usage: %s <tape-file> [output-file]\n' "$0" >&2
+    exit 1
+fi
+
+if ! command -v vhs >/dev/null 2>&1; then
+    printf '%s\n' 'vhs is required to render terminal recordings.' >&2
+    exit 1
+fi
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TAPE_FILE="$1"
+OUTPUT_FILE="${2:-}"
+
+cd "$ROOT_DIR"
+vhs validate "$TAPE_FILE"
+
+if [ -n "$OUTPUT_FILE" ]; then
+    vhs -o "$OUTPUT_FILE" "$TAPE_FILE"
+else
+    vhs "$TAPE_FILE"
+fi