From dc83a55555873be007fd0742a700b6915bb2743f Mon Sep 17 00:00:00 2001 From: mptyl Date: Fri, 14 Aug 2026 18:41:34 +0200 Subject: [PATCH] docs: correct Pi operator recovery guidance --- docs/contracts/thothctl-pi.md | 6 +++++- docs/install/pi-management.md | 27 ++++++++++++++---------- scripts/verify-workspace-install-docs.sh | 10 ++++++--- 3 files changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/contracts/thothctl-pi.md b/docs/contracts/thothctl-pi.md index 3b56ddb2..4c4e09bf 100644 --- a/docs/contracts/thothctl-pi.md +++ b/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 diff --git a/docs/install/pi-management.md b/docs/install/pi-management.md index 26c62751..b86fa0d0 100644 --- a/docs/install/pi-management.md +++ b/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 -container, or a host-native Pi directory. +management rejects executable `!command` values. Docker Compose mounts the selected configuration +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 -recovery path: +For a failed restart, use maintenance recovery instead of rollback. After repairing the reported +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 -installers, alter files inside the live container, mount the Docker socket, expose a browser shell, -or use a host Pi as a substitute. +`thothctl pi doctor`, `thothctl pi test`, and `thothctl pi logs` commands. diff --git a/scripts/verify-workspace-install-docs.sh b/scripts/verify-workspace-install-docs.sh index 0b8eef3f..a44aaf43 100755 --- a/scripts/verify-workspace-install-docs.sh +++ b/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" \ - "no browser shell" \ - "does not mount the Docker socket" + "Raw Compose access is unsupported" 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");