Align quickstart guidance across docs and CLI

README.md

@@ -18,6 +18,7 @@ It exposes the same runtime in three public forms:
 - 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/)
+- What's new in 2.0: [CHANGELOG.md#200](CHANGELOG.md#200)
 - Host requirements: [docs/host-requirements.md](docs/host-requirements.md)
 - Integration targets: [docs/integrations.md](docs/integrations.md)
 - Public contract: [docs/public-contract.md](docs/public-contract.md)
@@ -26,24 +27,35 @@ It exposes the same runtime in three public forms:
 
 ## Quickstart
 
-Canonical published-package path:
+Use either of these equivalent quickstart paths:
 
 ```bash
+# Package without install
 python -m pip install uv
 uvx --from pyro-mcp pyro doctor
+uvx --from pyro-mcp pyro env list
 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`.
+```bash
+# Already installed
+pyro doctor
+pyro env list
+pyro env pull debian:12
+pyro run debian:12 -- git --version
+```
+
+From a repo checkout, replace `pyro` with `uv run pyro`.
 
 What success looks like:
 
 ```bash
 Platform: linux-x86_64
 Runtime: PASS
+Catalog version: 2.0.0
 ...
 Pulled: debian:12
 ...
@@ -56,7 +68,6 @@ access to `registry-1.docker.io`, and needs local cache space for the guest imag
 
 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)
 
@@ -102,7 +113,7 @@ Capabilities: vm_boot=yes guest_exec=yes guest_network=yes
 Networking: tun=yes ip_forward=yes
 ```
 
-### 2. Inspect the catalog and pull the default environment
+### 2. Inspect the catalog
 
 ```bash
 uvx --from pyro-mcp pyro env list
@@ -117,6 +128,8 @@ debian:12-base [installed|not installed] Minimal Debian 12 environment for shell
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
 ```
 
+### 3. Pull the default environment
+
 ```bash
 uvx --from pyro-mcp pyro env pull debian:12
 ```
@@ -125,7 +138,7 @@ The first pull downloads an OCI environment from public Docker Hub, requires out
 access to `registry-1.docker.io`, and needs local cache space for the guest image.
 See [docs/host-requirements.md](docs/host-requirements.md) for the full host requirements.
 
-### 3. Run one command in a guest
+### 4. Run one command in a guest
 
 ```bash
 uvx --from pyro-mcp pyro run debian:12 -- git --version
@@ -142,7 +155,7 @@ The guest command output and the `[run] ...` summary are written to different st
 may appear in either order in terminals or capture tools. Use `--json` if you need a
 deterministic structured result.
 
-### 4. Optional demos
+### 5. Optional demos
 
 ```bash
 uvx --from pyro-mcp pyro demo

docs/first-run.md

@@ -2,8 +2,9 @@
 
 This is the intended evaluator path for a first successful run on a supported host.
 Copy the commands as-is. Paths and timing values will differ on your machine.
-If you are running from a source checkout instead of the published package, replace
+The same sequence works with an installed `pyro` binary by dropping the
-`uvx --from pyro-mcp pyro` with `uv run pyro`.
+`uvx --from pyro-mcp` prefix. If you are running from a source checkout instead
+of the published package, replace `pyro` with `uv run pyro`.
 
 ## 1. Verify the host
 

docs/install.md

@@ -35,9 +35,25 @@ Use these command forms consistently:
 
 ## Fastest Evaluation Path
 
-Use the package directly without a manual install:
+Use either of these equivalent evaluator paths:
 
-If you are running from a repo checkout instead, replace `uvx --from pyro-mcp pyro` with `uv run pyro`.
+```bash
+# Package without install
+uvx --from pyro-mcp pyro doctor
+uvx --from pyro-mcp pyro env list
+uvx --from pyro-mcp pyro env pull debian:12
+uvx --from pyro-mcp pyro run debian:12 -- git --version
+```
+
+```bash
+# Already installed
+pyro doctor
+pyro env list
+pyro env pull debian:12
+pyro run debian:12 -- git --version
+```
+
+If you are running from a repo checkout instead, replace `pyro` with `uv run pyro`.
 
 ### 1. Check the host first
 
@@ -133,6 +149,8 @@ When you are done evaluating and want to remove stale cached environments, run `
 
 ## Installed CLI
 
+If you already installed the package, the same evaluator path works with plain `pyro ...`:
+
 ```bash
 uv tool install pyro-mcp
 pyro --version

src/pyro_mcp/cli.py

@@ -168,6 +168,7 @@ def _build_parser() -> argparse.ArgumentParser:
             """
             Suggested first run:
               pyro doctor
+              pyro env list
               pyro env pull debian:12
               pyro run debian:12 -- git --version
 

tests/test_cli.py

@@ -27,6 +27,7 @@ def test_cli_help_guides_first_run() -> None:
 
     assert "Suggested first run:" in help_text
     assert "pyro doctor" in help_text
+    assert "pyro env list" in help_text
     assert "pyro env pull debian:12" in help_text
     assert "pyro run debian:12 -- git --version" in help_text
     assert "Use `pyro mcp serve` only after the CLI validation path works." in help_text