Add workspace handoff shortcuts and file-backed inputs

Remove the remaining shell glue from the canonical CLI workspace flows so users can hand off IDs and host-authored text files directly.

Add --id-only on workspace create and shell open, plus --text-file and --patch-file for workspace file write and patch apply, while keeping the underlying SDK, MCP, and backend behavior unchanged.

Update the top walkthroughs, contract docs, roadmap status, and use-case smoke runner to use the new shortcuts, and verify the milestone with uv lock, make check, make dist-check, focused CLI tests, and a real guest-backed smoke for create, file write, patch apply, and shell open/read.

docs/install.md

@@ -85,7 +85,7 @@ uvx --from pyro-mcp pyro env list
 Expected output:
 
 ```bash
-Catalog version: 3.6.0
+Catalog version: 3.7.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.
@@ -140,12 +140,12 @@ 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 --name repro-fix --label issue=123 --json | python -c 'import json,sys; print(json.load(sys.stdin)["workspace_id"])')"
+WORKSPACE_ID="$(pyro workspace create debian:12 --seed-path ./repo --name repro-fix --label issue=123 --id-only)"
 pyro workspace list
 pyro workspace update "$WORKSPACE_ID" --label owner=codex
 pyro workspace sync push "$WORKSPACE_ID" ./changes
 pyro workspace file read "$WORKSPACE_ID" note.txt
-pyro workspace patch apply "$WORKSPACE_ID" --patch "$(cat fix.patch)"
+pyro workspace patch apply "$WORKSPACE_ID" --patch-file fix.patch
 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'
@@ -221,12 +221,12 @@ After the CLI path works, you can move on to:
 - live workspace updates: `pyro workspace sync push WORKSPACE_ID ./changes`
 - guest networking policy: `pyro workspace create debian:12 --network-policy egress`
 - workspace secrets: `pyro workspace create debian:12 --secret API_TOKEN=expected --secret-file PIP_TOKEN=./token.txt`
-- model-native file editing: `pyro workspace file read WORKSPACE_ID src/app.py`, `pyro workspace file write WORKSPACE_ID src/app.py --text 'print("hi")'`, and `pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"`
+- model-native file editing: `pyro workspace file read WORKSPACE_ID src/app.py`, `pyro workspace file write WORKSPACE_ID src/app.py --text-file ./app.py`, and `pyro workspace patch apply WORKSPACE_ID --patch-file fix.patch`
 - baseline diff: `pyro workspace diff WORKSPACE_ID`
 - snapshots and reset: `pyro workspace snapshot create WORKSPACE_ID checkpoint` and `pyro workspace reset WORKSPACE_ID --snapshot checkpoint`
 - host export: `pyro workspace export WORKSPACE_ID note.txt --output ./note.txt`
 - stopped-workspace inspection: `pyro workspace stop WORKSPACE_ID`, `pyro workspace disk list WORKSPACE_ID`, `pyro workspace disk read WORKSPACE_ID note.txt`, and `pyro workspace disk export WORKSPACE_ID --output ./workspace.ext4`
-- interactive shells: `pyro workspace shell open WORKSPACE_ID`
+- interactive shells: `pyro workspace shell open WORKSPACE_ID --id-only`
 - long-running services: `pyro workspace service start WORKSPACE_ID app --ready-file .ready -- sh -lc 'touch .ready && while true; do sleep 60; done'`
 - localhost-published ports: `pyro workspace create debian:12 --network-policy egress+published-ports` and `pyro workspace service start WORKSPACE_ID app --ready-http http://127.0.0.1:8080/ --publish 18080:8080 -- ./start-app`
 - MCP: `pyro mcp serve --profile workspace-core`
@@ -245,8 +245,8 @@ pyro workspace create debian:12 --network-policy egress+published-ports
 pyro workspace sync push WORKSPACE_ID ./changes --dest src
 pyro workspace file list WORKSPACE_ID src --recursive
 pyro workspace file read WORKSPACE_ID src/note.txt
-pyro workspace file write WORKSPACE_ID src/app.py --text 'print("hi")'
-pyro workspace patch apply WORKSPACE_ID --patch "$(cat fix.patch)"
+pyro workspace file write WORKSPACE_ID src/app.py --text-file ./app.py
+pyro workspace patch apply WORKSPACE_ID --patch-file fix.patch
 pyro workspace exec WORKSPACE_ID -- cat src/note.txt
 pyro workspace exec WORKSPACE_ID --secret-env API_TOKEN -- sh -lc 'test "$API_TOKEN" = "expected"'
 pyro workspace diff WORKSPACE_ID
@@ -254,7 +254,7 @@ pyro workspace snapshot create WORKSPACE_ID checkpoint
 pyro workspace reset WORKSPACE_ID --snapshot checkpoint
 pyro workspace reset WORKSPACE_ID
 pyro workspace export WORKSPACE_ID src/note.txt --output ./note.txt
-pyro workspace shell open WORKSPACE_ID --secret-env API_TOKEN
+pyro workspace shell open WORKSPACE_ID --secret-env API_TOKEN --id-only
 pyro workspace shell write WORKSPACE_ID SHELL_ID --input 'pwd'
 pyro workspace shell read WORKSPACE_ID SHELL_ID --plain --wait-for-idle-ms 300
 pyro workspace shell close WORKSPACE_ID SHELL_ID
@@ -276,10 +276,11 @@ pyro workspace delete WORKSPACE_ID
 ```
 
 Workspace commands default to the persistent `/workspace` directory inside the guest. If you need
-the identifier programmatically, use `--json` and read the `workspace_id` field. Use `--seed-path`
+the identifier programmatically, use `--id-only` for only the identifier or `--json` for the full
+workspace payload. Use `--seed-path`
 when the workspace should start from a host directory or a local `.tar` / `.tar.gz` / `.tgz`
 archive. Use `pyro workspace sync push` for later host-side changes to a started workspace. Sync
-is non-atomic in `3.6.0`; if it fails partway through, prefer `pyro workspace reset` to recover
+is non-atomic in `3.7.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 current workspace
 tree to its immutable create-time baseline, `pyro workspace snapshot *` to capture named
 checkpoints, and `pyro workspace export` to copy one changed file or directory back to the host. Use