docs: correct Pi operator recovery guidance

docs/contracts/thothctl-pi.md

@@ -169,12 +169,16 @@ the settings volume. It does not require the failed candidate, a host Node runti
 socket inside a container. The restored core is then recreated, verified, and rescanned before the
 gate can open.
 
-For an interrupted transaction, first run:
+For a failed update with `update-state.json`, first run:
 
 ```text
 thothctl --installation /absolute/path/thothii-installation.yaml pi rollback --yes
 ```
 
+Rollback operates on update state only. A failed restart with `restart-state.json` retains its
+current image and has no candidate image to roll back; first inspect status and logs, repair the
+reported problem, then use maintenance recovery.
+
 Inspect and clean a stale durable gate with:
 
 ```text

docs/install/pi-management.md

@@ -2,7 +2,7 @@
 
 ThothII bundles Pi in the `core` image. Operators use the Pi Management page for safe application
 defaults and the host-side `thothctl` CLI for lifecycle work. A local Pi installation is not
-required; the core container does not mount the Docker socket and there is no browser shell.
+required.
 
 In the commands below, replace `/absolute/path/to/thothii-installation.yaml` with the protected
 installation descriptor created by the [local installation guide](local.md).
@@ -26,7 +26,8 @@ Alternatively, use the CLI from an administrator terminal:
 ```
 
 Use GUI Save defaults or CLI `pi configure`, not both for the same change. The CLI's interactive
-choices are restricted to supported models; non-interactive use must supply all three values.
+choices are restricted to supported models; non-interactive use must supply all three values. Both
+methods store application defaults in backend installation settings, not in the project policy file.
 
 Useful read-only checks are:
 
@@ -47,11 +48,12 @@ normal project process:
 
 - `deploy/pi/models.json` is the provider catalog: provider endpoints and the models each provider
   offers.
-- `deploy/pi/settings.json` is the enabled-model policy and application defaults.
+- `deploy/pi/settings.json` is the enabled-model policy only; it lists the models available to the
+  application and does not store application defaults.
 
 These files contain configuration, not credentials. Keep provider configuration declarative: Pi
-management rejects executable `!command` values. Do not edit generated files, the running
+management rejects executable `!command` values. Docker Compose mounts the selected configuration
-container, or a host-native Pi directory.
+and credential files read-only.
 
 ## Store provider credentials
 
@@ -109,17 +111,22 @@ volumes.
 
 If a restart or update fails after core recreation, leave maintenance enabled and preserve the
 reported recovery state. Do not delete `.thothctl`, state files, containers, or volumes. Inspect
-status and sanitized logs, then restore the previous image when an update is involved:
+status and sanitized logs:
 
 ```sh
 "$THTCTL" --installation "$INSTALLATION" pi maintenance status
 "$THTCTL" --installation "$INSTALLATION" pi status
 "$THTCTL" --installation "$INSTALLATION" pi logs
+```
+
+For a failed update, restore its prior image:
+
+```sh
 "$THTCTL" --installation "$INSTALLATION" pi rollback --yes
 ```
 
-Repair the reported Docker, disk, or configuration problem, then have ThothII complete the safe
+For a failed restart, use maintenance recovery instead of rollback. After repairing the reported
-recovery path:
+Docker, disk, or configuration problem, use the same command to complete either safe recovery path:
 
 ```sh
 "$THTCTL" --installation "$INSTALLATION" pi maintenance recover --yes
@@ -135,6 +142,4 @@ installation gated and collect only the sanitized diagnostics.
 
 Raw Compose access is unsupported because it can bypass the installation-specific environment and
 durable image selector. For support, use the installation-aware `thothctl pi status`,
-`thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands. Do not run package
+`thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands.
-installers, alter files inside the live container, mount the Docker socket, expose a browser shell,
-or use a host Pi as a substitute.

scripts/verify-workspace-install-docs.sh

@@ -1153,6 +1153,8 @@ verify_pi_management_guide() {
     "restart only core" \
     "deploy/pi/models.json" \
     "deploy/pi/settings.json" \
+    "policy only" \
+    "backend installation settings" \
     "PI_AUTH_FILE" \
     "pi update" \
     "pi rollback --yes" \
@@ -1160,13 +1162,15 @@ verify_pi_management_guide() {
     "pi maintenance recover --yes" \
     "pi logs" \
     "/run/secrets" \
-    "Raw Compose access is unsupported" \
+    "Raw Compose access is unsupported"
-    "no browser shell" \
-    "does not mount the Docker socket"
   if grep -Fq '~/.pi/agent/' "$guide"; then
     echo "Pi management guide must not direct ThothII operators to native Pi paths" >&2
     return 1
   fi
+  if grep -Eqi 'browser shell|host-native Pi|host Pi|running container|live container' "$guide"; then
+    echo "Pi management guide must not include native-Pi, browser-shell, or live-container workflow" >&2
+    return 1
+  fi
   node - "$guide" <<'NODE'
 const fs = require("fs");
 const source = fs.readFileSync(process.argv[2], "utf8");