diff --git a/README.md b/README.md
index d2026e3..2fa78c9 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,42 @@ It exposes the same runtime in three public forms:
 - Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 
+## Quickstart
+
+Canonical published-package path:
+
+```bash
+python -m pip install uv
+uvx --from pyro-mcp pyro doctor
+uvx --from pyro-mcp pyro env pull debian:12
+uvx --from pyro-mcp pyro run debian:12 -- git --version
+```
+
+![Quickstart walkthrough](docs/assets/first-run.gif)
+
+From a repo checkout, replace `uvx --from pyro-mcp pyro` with `uv run pyro`.
+
+What success looks like:
+
+```bash
+Platform: linux-x86_64
+Runtime: PASS
+...
+Pulled: debian:12
+...
+[run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+git version ...
+```
+
+The first pull downloads an OCI environment from public Docker Hub, requires outbound HTTPS
+access to `registry-1.docker.io`, and needs local cache space for the guest image.
+
+After the quickstart works:
+
+- inspect the catalog with `uvx --from pyro-mcp pyro env list`
+- prove the full one-shot lifecycle with `uvx --from pyro-mcp pyro demo`
+- move to Python or MCP via [docs/integrations.md](docs/integrations.md)
+
 ## Supported Hosts
 
 Supported today:
@@ -45,30 +81,9 @@ Not supported today:
 - Windows
 - Linux hosts without working KVM at `/dev/kvm`
 
-If you do not already have `uv`, install it first:
+## Detailed Walkthrough
 
-```bash
-python -m pip install uv
-```
-
-Published package path:
-
-```bash
-uvx --from pyro-mcp pyro doctor
-uv tool install pyro-mcp
-```
-
-Source checkout path:
-
-```bash
-uv run pyro doctor
-```
-
-## 5-Minute Evaluation
-
-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`.
+If you want the expanded version of the canonical quickstart, use the step-by-step flow below.
 
 ### 1. Check the host
 
diff --git a/docs/assets/first-run.gif b/docs/assets/first-run.gif
index 3883cc8..981e11d 100644
Binary files a/docs/assets/first-run.gif and b/docs/assets/first-run.gif differ
diff --git a/docs/assets/first-run.tape b/docs/assets/first-run.tape
index d5574c7..ce6ea1e 100644
--- a/docs/assets/first-run.tape
+++ b/docs/assets/first-run.tape
@@ -5,7 +5,7 @@ Require uv
 Set Shell "zsh"
 Set FontSize 18
 Set Width 1200
-Set Height 820
+Set Height 760
 Set Theme "Dracula"
 Set TypingSpeed 35ms
 Set Padding 24
@@ -16,35 +16,29 @@ Type "cd /home/thales/projects/personal/pyro"
 Enter
 Type "export UV_CACHE_DIR=.uv-cache"
 Enter
+Type "export PYRO_ENVIRONMENT_CACHE_DIR=$(mktemp -d)"
+Enter
+Type "uvx --from pyro-mcp pyro --version >/dev/null"
+Enter
 Show
 
-Type "printf '\\n# Check host support from the repo checkout\\n'"
+Type "# Check that the host can boot and run guests"
 Enter
-Sleep 800ms
-Type "uv run pyro doctor"
+Sleep 700ms
+Type "uvx --from pyro-mcp pyro doctor"
 Enter
 Sleep 2200ms
 
-Type "printf '\\n# Inspect and pull the default environment\\n'"
+Type "# Pull the default environment into a fresh local cache"
 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"
+Sleep 700ms
+Type "uvx --from pyro-mcp pyro env pull debian:12"
 Enter
 Sleep 2200ms
 
-Type "printf '\\n# Prove the one-shot VM lifecycle demo\\n'"
+Type "# Run one isolated command inside an ephemeral microVM"
 Enter
-Sleep 800ms
-Type "uv run pyro demo"
+Sleep 700ms
+Type "uvx --from pyro-mcp pyro run debian:12 -- git --version"
 Enter
 Sleep 2600ms