feat: finish Pi and workspace management updates

docs/contracts/thothctl-pi.md

@@ -6,13 +6,18 @@ does not mount a Docker socket, and Pi is never updated in a running container.
 ## Inspection and configuration
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi status
-thothctl --installation /absolute/path/thothii-installation.yaml pi doctor
-thothctl --installation /absolute/path/thothii-installation.yaml pi test
-thothctl --installation /absolute/path/thothii-installation.yaml pi logs
-thothctl --installation /absolute/path/thothii-installation.yaml pi configure
+thothctl pi status
+thothctl pi doctor
+thothctl pi test
+thothctl pi logs
+thothctl pi configure
 ```
 
+When `--installation` is omitted, `thothctl` first uses `THOTHII_INSTALLATION` and otherwise
+discovers one valid `thothii-installation.yaml` in the current project tree, including an immediate
+`deploy/*` directory. Use `--installation /absolute/path/thothii-installation.yaml` as an explicit
+override when the descriptor is outside that tree or more than one installation is available.
+
 `status` executes the image-bundled `pi --version`. `doctor` compares that value with both the
 container's `PI_VERSION` contract and the `io.thothii.pi.version` image label; a merely nonempty
 version is not sufficient. `doctor` and `test` also require a healthy core, a successful Pi smoke,
@@ -25,7 +30,7 @@ models come from the backend's closed model list, and the model choices are rest
 selected provider. In non-interactive use, all choices must be explicit:
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi configure \
+thothctl pi configure \
   --provider zai --model glm-5.2 --thinking medium
 ```
 
@@ -70,7 +75,7 @@ secret overrides must never bypass that preflight wrapper.
 Configuration reload is a separate lifecycle operation from an image update:
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi restart --yes [--drain]
+thothctl pi restart --yes [--drain]
 ```
 
 `--yes` is required after reviewing the planned core recreation. Restart activates the durable
@@ -104,13 +109,25 @@ recovery rather than deleting recovery material.
 
 ## Updating Pi
 
-Every update requires a pinned version, an explicit source, and confirmation:
+The normal update uses the repository's pinned version and build source automatically:
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi update \
-  --version 0.81.0 --source build --yes
+thothctl pi update
+thothctl pi update --version 0.81.0
+```
 
-thothctl --installation /absolute/path/thothii-installation.yaml pi update \
+With no `--version`, the command reads the single default `ARG PI_VERSION=<version>` from
+`docker/core.Dockerfile` in the selected project. The normal path confirms the explicit update
+command, drains active sessions without terminating them, builds the candidate, recreates only
+`core`, verifies it, and promotes it transactionally.
+
+Advanced registry updates remain available and require an immutable digest:
+
+```text
+thothctl pi update \
+  --version 0.81.0 --source build --yes --drain
+
+thothctl pi update \
   --version 0.81.0 --source pull \
   --image registry.example.invalid/thothii-core@sha256:<64-lowercase-hex-digits> --yes
 ```
@@ -178,7 +195,7 @@ gate can open.
 For a failed update with `update-state.json`, first run:
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi rollback --yes
+thothctl pi rollback --yes
 ```
 
 Rollback restores the image recorded in update state, but it checks restart state before making any
@@ -189,8 +206,8 @@ reported problem, then use maintenance recovery.
 Inspect and clean a stale durable gate with:
 
 ```text
-thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance status
-thothctl --installation /absolute/path/thothii-installation.yaml pi maintenance recover --yes
+thothctl pi maintenance status
+thothctl pi maintenance recover --yes
 ```
 
 `maintenance recover` restores the captured restart image pin and lifecycle override when needed,