Promote stable workspace product for 3.0.0

Freeze the current workspace-first surface as the stable 3.0 contract and reposition the
landing docs, CLI help, and public contract around the stable workspace path after the
one-shot proof.

Bump the package and catalog compatibility to 3.0.0, add a dedicated workspace walkthrough
tape/GIF, and mark the 3.0.0 roadmap milestone done while keeping runtime capability
unchanged in this release.

Validation: uv lock; UV_CACHE_DIR=.uv-cache make check; UV_CACHE_DIR=.uv-cache make dist-check;
UV_CACHE_DIR=.uv-cache uv build; UV_CACHE_DIR=.uv-cache uvx --from twine twine check dist/*;
built-wheel CLI smoke for pyro --help and pyro workspace --help; vhs validate plus rendered
workspace-first-run.gif outside the sandbox because vhs crashes when sandboxed.

README.md

@@ -1,10 +1,10 @@
 # pyro-mcp
 
-`pyro-mcp` runs one-shot commands and repeated workspaces inside ephemeral Firecracker microVMs using curated Linux environments such as `debian:12`.
+`pyro-mcp` is a stable agent workspace product for one-shot commands and persistent work 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.
+This is for coding agents, MCP clients, and developers who want isolated command execution and stable disposable workspaces in ephemeral microVMs.
 
 It exposes the same runtime in three public forms:
 
@@ -18,9 +18,10 @@ It exposes the same runtime in three public forms:
 - Vision: [docs/vision.md](docs/vision.md)
 - Workspace roadmap: [docs/roadmap/task-workspace-ga.md](docs/roadmap/task-workspace-ga.md)
 - First run transcript: [docs/first-run.md](docs/first-run.md)
+- Stable workspace walkthrough GIF: [docs/assets/workspace-first-run.gif](docs/assets/workspace-first-run.gif)
 - 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.10.0: [CHANGELOG.md#2100](CHANGELOG.md#2100)
+- What's new in 3.0.0: [CHANGELOG.md#300](CHANGELOG.md#300)
 - 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)
@@ -57,7 +58,7 @@ What success looks like:
 ```bash
 Platform: linux-x86_64
 Runtime: PASS
-Catalog version: 2.10.0
+Catalog version: 3.0.0
 ...
 [pull] phase=install environment=debian:12
 [pull] phase=ready environment=debian:12
@@ -73,6 +74,40 @@ 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.
 
+## Stable Workspace Path
+
+`pyro run` is the stable one-shot entrypoint. `pyro workspace ...` is the stable path when an
+agent needs one sandbox to stay alive across repeated commands, shells, services, checkpoints,
+diffs, exports, and reset.
+
+The commands below use plain `pyro ...`. Run the same flow with `uvx --from pyro-mcp pyro ...`
+for the published package, or `uv run pyro ...` from a source checkout.
+
+```bash
+uv tool install pyro-mcp
+WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --json | python -c 'import json,sys; print(json.load(sys.stdin)["workspace_id"])')"
+pyro workspace sync push "$WORKSPACE_ID" ./changes
+pyro workspace exec "$WORKSPACE_ID" -- cat note.txt
+pyro workspace snapshot create "$WORKSPACE_ID" checkpoint
+pyro workspace service start "$WORKSPACE_ID" web --ready-file .web-ready -- sh -lc 'touch .web-ready && while true; do sleep 60; done'
+pyro workspace reset "$WORKSPACE_ID" --snapshot checkpoint
+pyro workspace export "$WORKSPACE_ID" note.txt --output ./note.txt
+pyro workspace delete "$WORKSPACE_ID"
+```
+
+![Stable workspace walkthrough](docs/assets/workspace-first-run.gif)
+
+That stable workspace path gives you:
+
+- initial host-in seeding with `--seed-path`
+- later host-in updates with `workspace sync push`
+- one-shot commands with `workspace exec` and persistent PTYs with `workspace shell *`
+- long-running processes with `workspace service *`
+- explicit checkpoints with `workspace snapshot *`
+- full-sandbox recovery with `workspace reset`
+- baseline comparison with `workspace diff`
+- explicit host-out export with `workspace export`
+
 After the quickstart works:
 
 - prove the full one-shot lifecycle with `uvx --from pyro-mcp pyro demo`
@@ -141,7 +176,7 @@ uvx --from pyro-mcp pyro env list
 Expected output:
 
 ```bash
-Catalog version: 2.10.0
+Catalog version: 3.0.0
 debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
 debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
 debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
@@ -205,7 +240,7 @@ When you are done evaluating and want to remove stale cached environments, run `
 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).
 
-## Persistent Workspaces
+## Stable Workspaces
 
 Use `pyro run` for one-shot commands. Use `pyro workspace ...` when you need repeated commands in one
 workspace without recreating the sandbox every time.
@@ -248,7 +283,7 @@ Persistent workspaces start in `/workspace` and keep command history until you d
 machine consumption, add `--json` and read the returned `workspace_id`. Use `--seed-path` when
 you want the workspace to start from a host directory or a local `.tar` / `.tar.gz` / `.tgz`
 archive instead of an empty workspace. Use `pyro workspace sync push` when you want to import
-later host-side changes into a started workspace. Sync is non-atomic in `2.10.0`; if it fails
+later host-side changes into a started workspace. Sync is non-atomic in `3.0.0`; if it fails
 partway through, prefer `pyro workspace reset` to recover from `baseline` or one named snapshot.
 Use `pyro workspace diff` to compare the live `/workspace` tree to its immutable create-time
 baseline, and `pyro workspace export` to copy one changed file or directory back to the host. Use