Clarify package install and run expectations

README.md

@@ -12,6 +12,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)
+- 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)
 - Public contract: [docs/public-contract.md](docs/public-contract.md)
@@ -45,6 +46,19 @@ If you do not already have `uv`, install it first:
 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:
@@ -85,6 +99,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com
 uvx --from pyro-mcp pyro env pull debian:12
 ```
 
+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.
+See [docs/host-requirements.md](docs/host-requirements.md) for the full host requirements.
+
 ### 3. Run one command in a guest
 
 ```bash
@@ -94,10 +112,14 @@ uvx --from pyro-mcp pyro run debian:12 -- git --version
 Expected success signals:
 
 ```bash
-git version ...
 [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+git version ...
 ```
 
+The guest command output and the `[run] ...` summary are written to different streams, so they
+may appear in either order in terminals or capture tools. Use `--json` if you need a
+deterministic structured result.
+
 ### 4. Optional demos
 
 ```bash
@@ -115,6 +137,12 @@ The public user-facing interface is `pyro` and `Pyro`. After the CLI validation
 - `from pyro_mcp import Pyro` for Python orchestration
 - `pyro mcp serve` for MCP clients
 
+Command forms:
+
+- published package without install: `uvx --from pyro-mcp pyro ...`
+- installed package: `pyro ...`
+- source checkout: `uv run pyro ...`
+
 `Makefile` targets are contributor conveniences for this repository and are not the primary product UX.
 
 ## Official Environments

docs/first-run.md

@@ -2,6 +2,8 @@
 
 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
+`uvx --from pyro-mcp pyro` with `uv run pyro`.
 
 ## 1. Verify the host
 
@@ -27,6 +29,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com
 
 ## 3. Pull the default environment
 
+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. See
+[host-requirements.md](host-requirements.md) for the full host requirements.
+
 ```bash
 $ uvx --from pyro-mcp pyro env pull debian:12
 Pulled: debian:12
@@ -46,10 +52,14 @@ OCI source: registry-1.docker.io/thalesmaciel/pyro-environment-debian-12:1.0.0
 
 ```bash
 $ uvx --from pyro-mcp pyro run debian:12 -- git --version
-git version ...
 [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+git version ...
 ```
 
+The guest command output and the `[run] ...` summary are written to different streams, so they
+may appear in either order in terminals or capture tools. Use `--json` if you need a
+deterministic structured result.
+
 ## 5. Optional next steps
 
 ```bash

docs/install.md

@@ -27,6 +27,12 @@ If you do not already have `uv`, install it first:
 python -m pip install uv
 ```
 
+Use these command forms consistently:
+
+- published package without install: `uvx --from pyro-mcp pyro ...`
+- installed package: `pyro ...`
+- source checkout: `uv run pyro ...`
+
 ## Fastest Evaluation Path
 
 Use the package directly without a manual install:
@@ -71,6 +77,10 @@ debian:12-build [installed|not installed] Debian 12 environment with Git and com
 uvx --from pyro-mcp pyro env pull debian:12
 ```
 
+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. See
+[host-requirements.md](host-requirements.md) for the full host requirements.
+
 ### 4. Run one command in a guest
 
 ```bash
@@ -80,10 +90,14 @@ uvx --from pyro-mcp pyro run debian:12 -- git --version
 Expected success signals:
 
 ```bash
-git version ...
 [run] environment=debian:12 execution_mode=guest_vsock exit_code=0 duration_ms=...
+git version ...
 ```
 
+The guest command output and the `[run] ...` summary are written to different streams, so they
+may appear in either order in terminals or capture tools. Use `--json` if you need a
+deterministic structured result.
+
 If guest execution is unavailable, the command fails unless you explicitly pass
 `--allow-host-compat`.
 

pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
 Homepage = "https://git.thaloco.com/thaloco/pyro-mcp"
 Repository = "https://git.thaloco.com/thaloco/pyro-mcp"
 Issues = "https://git.thaloco.com/thaloco/pyro-mcp/issues"
+PyPI = "https://pypi.org/project/pyro-mcp/"
 
 [project.scripts]
 pyro = "pyro_mcp.cli:main"

src/pyro_mcp/cli.py

@@ -209,8 +209,19 @@ def _build_parser() -> argparse.ArgumentParser:
     pull_parser = env_subparsers.add_parser(
         "pull",
         help="Install an environment into the local cache.",
-        description="Download and install one official environment into the local cache.",
+        description=(
-        epilog="Example:\n  pyro env pull debian:12",
+            "Download and install one official environment into the local cache from "
+            "the configured OCI registry."
+        ),
+        epilog=dedent(
+            """
+            Example:
+              pyro env pull debian:12
+
+            The first pull downloads from public Docker Hub, requires outbound HTTPS,
+            and needs local cache space for the guest image.
+            """
+        ),
         formatter_class=_HelpFormatter,
     )
     pull_parser.add_argument(
@@ -288,6 +299,10 @@ def _build_parser() -> argparse.ArgumentParser:
             Examples:
               pyro run debian:12 -- git --version
               pyro run debian:12 --network -- git ls-remote https://github.com/octocat/Hello-World.git
+
+            The guest command output and the [run] summary are written to different
+            streams, so they may appear in either order. Use --json for a deterministic
+            structured result.
             """
         ),
         formatter_class=_HelpFormatter,

tests/test_cli.py

@@ -39,10 +39,13 @@ def test_cli_subcommand_help_includes_examples_and_guidance() -> None:
     assert "pyro run debian:12 -- git --version" in run_help
     assert "Opt into host-side compatibility execution" in run_help
     assert "Enable outbound guest networking" in run_help
+    assert "may appear in either order" in run_help
+    assert "Use --json for a deterministic" in run_help
 
     env_help = _subparser_choice(_subparser_choice(parser, "env"), "pull").format_help()
     assert "Environment name from `pyro env list`" in env_help
     assert "pyro env pull debian:12" in env_help
+    assert "downloads from public Docker Hub" in env_help
 
     doctor_help = _subparser_choice(parser, "doctor").format_help()
     assert "Check host prerequisites and embedded runtime health" in doctor_help