Refresh release docs for Docker Hub environments

README.md

@@ -42,8 +42,9 @@ Current official environments in the shipped catalog:
 - `debian:12-build`
 
 The package ships the embedded Firecracker runtime and a package-controlled environment catalog.
-Official environments are pulled as OCI artifacts from Docker Hub into a local cache on first use or
+Official environments are pulled as OCI artifacts from public Docker Hub repositories into a local
-through `pyro env pull`.
+cache on first use or through `pyro env pull`.
+End users do not need registry credentials to pull or run official environments.
 
 ## CLI
 
@@ -198,13 +199,16 @@ Official environment publication is automated through
 For a local publish against Docker Hub:
 
 ```bash
+export DOCKERHUB_USERNAME='your-dockerhub-username'
+export DOCKERHUB_TOKEN='your-dockerhub-token'
 make runtime-materialize
-OCI_REGISTRY_USERNAME="$DOCKERHUB_USERNAME" OCI_REGISTRY_PASSWORD="$DOCKERHUB_TOKEN" \
 make runtime-publish-official-environments-oci
 ```
 
 `make runtime-publish-environment-oci` auto-exports the OCI layout for the selected
 environment if it is missing.
+The publisher accepts either `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` or
+`OCI_REGISTRY_USERNAME` and `OCI_REGISTRY_PASSWORD`.
 Docker Hub uploads are chunked by default for large rootfs layers; if you need to tune a slow
 link, use `PYRO_OCI_UPLOAD_TIMEOUT_SECONDS`, `PYRO_OCI_UPLOAD_CHUNK_SIZE_BYTES`, and
 `PYRO_OCI_REQUEST_TIMEOUT_SECONDS`.

docs/host-requirements.md

@@ -7,6 +7,7 @@
 - KVM available at `/dev/kvm`
 - support for Firecracker microVMs
 - sufficient disk for the embedded runtime files and cached OCI environment images
+- outbound HTTPS access to `registry-1.docker.io` for first-run installs or `pyro env pull`
 
 ## Required For Guest Networking
 

docs/install.md

@@ -4,6 +4,7 @@
 
 - Linux x86_64 host
 - Python 3.12+
+- `uv`
 - `/dev/kvm`
 
 If you want outbound guest networking:
@@ -20,6 +21,12 @@ Run the MCP server directly from the package without a manual install:
 uvx --from pyro-mcp pyro mcp serve
 ```
 
+Prefetch the default official environment:
+
+```bash
+uvx --from pyro-mcp pyro env pull debian:12
+```
+
 Run one command in a curated environment:
 
 ```bash
@@ -38,6 +45,7 @@ uvx --from pyro-mcp pyro env list
 uv tool install pyro-mcp
 pyro --version
 pyro env list
+pyro env pull debian:12
 pyro env inspect debian:12
 pyro doctor
 ```

docs/public-contract.md

@@ -45,9 +45,27 @@ Primary facade:
 
 - `Pyro`
 
-Supported public methods:
+Supported public entrypoints:
 
+- `create_server()`
 - `Pyro.create_server()`
+- `Pyro.list_environments()`
+- `Pyro.pull_environment(environment)`
+- `Pyro.inspect_environment(environment)`
+- `Pyro.prune_environments()`
+- `Pyro.create_vm(...)`
+- `Pyro.start_vm(vm_id)`
+- `Pyro.exec_vm(vm_id, *, command, timeout_seconds=30)`
+- `Pyro.stop_vm(vm_id)`
+- `Pyro.delete_vm(vm_id)`
+- `Pyro.status_vm(vm_id)`
+- `Pyro.network_info_vm(vm_id)`
+- `Pyro.reap_expired()`
+- `Pyro.run_in_vm(...)`
+
+Stable public method names:
+
+- `create_server()`
 - `list_environments()`
 - `pull_environment(environment)`
 - `inspect_environment(environment)`

docs/troubleshooting.md

@@ -7,6 +7,7 @@ Cause:
 - the environment cache directory is not writable
 - the configured registry artifact is unavailable
 - the environment download was interrupted
+- the host cannot reach `registry-1.docker.io`
 
 Fix:
 
@@ -16,6 +17,9 @@ pyro env prune
 pyro env pull debian:12
 ```
 
+If you are validating a freshly published official environment, also verify that the corresponding
+Docker Hub repository is public.
+
 ## `pyro run --network` fails before the guest starts
 
 Cause:

runtime_sources/README.md

@@ -17,14 +17,16 @@ Materialization workflow:
 
 Official environment publication workflow:
 1. `make runtime-materialize`
-2. `OCI_REGISTRY_USERNAME=... OCI_REGISTRY_PASSWORD=... make runtime-publish-official-environments-oci`
+2. `DOCKERHUB_USERNAME=... DOCKERHUB_TOKEN=... make runtime-publish-official-environments-oci`
 3. or run the repo workflow at `.github/workflows/publish-environments.yml` with Docker Hub credentials
 4. if your uplink is slow, tune publishing with `PYRO_OCI_UPLOAD_TIMEOUT_SECONDS`, `PYRO_OCI_UPLOAD_CHUNK_SIZE_BYTES`, and `PYRO_OCI_REQUEST_TIMEOUT_SECONDS`
 
+Official end-user pulls are anonymous; registry credentials are only required for publishing.
+
 Build requirements for the real path:
 - `docker`
 - outbound network access to GitHub and Debian snapshot mirrors
-- enough disk for a kernel build plus 2G ext4 images per profile
+- enough disk for a kernel build plus 2G ext4 images per source profile
 
 Kernel build note:
 - the kernel builder now defaults to conservative parallelism to avoid compiler crashes on memory-constrained hosts