# `3.1.0` Secondary Disk Tools

Status: Done

## Goal

Add stopped-workspace disk tools the vision explicitly places last, while keeping them secondary
to the stable workspace identity.

## Public API Changes

Shipped additions:

- `pyro workspace stop WORKSPACE_ID`
- `pyro workspace start WORKSPACE_ID`
- `pyro workspace disk export WORKSPACE_ID --output HOST_PATH`
- `pyro workspace disk list WORKSPACE_ID [PATH] [--recursive]`
- `pyro workspace disk read WORKSPACE_ID PATH [--max-bytes N]`
- matching Python SDK methods:
  - `stop_workspace`
  - `start_workspace`
  - `export_workspace_disk`
  - `list_workspace_disk`
  - `read_workspace_disk`
- matching MCP tools:
  - `workspace_stop`
  - `workspace_start`
  - `workspace_disk_export`
  - `workspace_disk_list`
  - `workspace_disk_read`

## Implementation Boundaries

- keep these tools scoped to stopped-workspace inspection, export, and offline workflows
- do not replace shell, exec, services, diff, export, or reset as the main
  interaction model
- prefer explicit stopped-workspace or offline semantics
- require guest-backed workspaces for `workspace disk *`
- keep disk export raw ext4 only in this milestone
- scrub runtime-only guest paths such as `/run/pyro-secrets`, `/run/pyro-shells`, and
  `/run/pyro-services` before offline inspection or export

## Non-Goals

- no drift into generic image tooling identity
- no replacement of workspace-level host crossing
- no disk import
- no disk mutation
- no create-from-disk workflow

## Acceptance Scenarios

- inspect or export a stopped workspace disk for offline analysis
- stop a workspace, inspect `/workspace` offline, export raw ext4, then start the same workspace
  again without resetting `/workspace`
- verify secret-backed workspaces scrub runtime-only guest paths before stopped-disk inspection

## Required Repo Updates

- docs that clearly mark disk tools as secondary
- examples that show when disk tools are faster than a full boot
- real smoke coverage for at least one offline inspection flow