From 1f6a49b985ed584a4864171529cf4198d63f25fb Mon Sep 17 00:00:00 2001 From: mptyl Date: Fri, 14 Aug 2026 17:09:58 +0200 Subject: [PATCH] docs: design Pi restart operator workflow --- ...-pi-management-operator-workflow-design.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md diff --git a/docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md b/docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md new file mode 100644 index 00000000..58db42c9 --- /dev/null +++ b/docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md @@ -0,0 +1,215 @@ +# Pi Management operator workflow design + +**Date:** 2026-08-14 +**Status:** Proposed + +## Context + +ThothII runs Pi only inside the Docker Compose `core` service. The current Pi Management dialog +mixes four different operations in one long instruction block: + +1. editing the host-side Pi provider catalog; +2. editing the host-side enabled-model policy; +3. selecting application defaults; and +4. upgrading the Pi version bundled in the `core` image. + +It also presents `thothctl pi configure` as mandatory even though the GUI already performs the same +provider/model/reasoning default update, repeats update guidance in a second section, copies an +incomplete `thothctl pi update` command, and exposes developer-only information about Vite and +frontend image rebuilding. + +There is also a real lifecycle gap. `thothctl pi update` safely replaces `core` when the Pi version +changes, but there is no Pi-specific command that reloads changed `models.json`, `settings.json`, or +credentials without changing the image. The documented fallback, `thothctl stop` followed by +`thothctl start`, restarts the whole installation. + +## Goals + +- Give a normal operator a short, structured, platform-specific workflow. +- Explain every operator-facing term before using it, especially `PI_AUTH_FILE`. +- Keep application defaults, Pi configuration files, credentials, configuration reload, and Pi + version updates conceptually separate. +- Add one safe command that recreates only `core` after host configuration or credentials change. +- Preserve the existing update transaction's session-drain, maintenance, verification, and + recovery guarantees. +- Remove duplicate, incomplete, native-Pi, developer-only, and raw-Compose guidance from the GUI. + +## Non-goals + +- The browser will not receive Docker access or a shell. +- The browser will not display or accept provider credentials. +- The GUI will not edit `deploy/pi/models.json`, `deploy/pi/settings.json`, or the credential file. +- `pi restart` will not build, pull, select, or upgrade an image. +- The general Pi internals document may continue to describe Pi's native paths, but it must clearly + state that ThothII operators edit the mounted host sources instead. + +## Operator concepts + +The revised interface will use the following terms consistently: + +- **Project root:** the ThothII checkout directory containing `compose.yaml` and the `deploy/` + directory. +- **Provider catalog:** `deploy/pi/models.json`. It declares provider endpoints and available model + metadata. A provider entry explains `baseUrl`, `api`, `models`, model `id`, and model `name`. +- **Enabled-model policy:** `deploy/pi/settings.json`. Its `enabledModels` array contains + `provider/model` identifiers that Pi is allowed to expose. +- **Application defaults:** provider, model, and reasoning stored in ThothII's persistent application + settings. The GUI's **Save defaults** action and `thothctl pi configure` are alternative interfaces + to this same setting; an operator does not run both. +- **Credential file:** the protected JSON file on the host whose location is assigned to + `PI_AUTH_FILE` in the installation environment file. Docker Compose mounts it read-only for Pi. + The GUI reports only whether a usable credential exists and never reveals its value. +- **Configuration reload:** recreation of the existing `core` container without changing its image. +- **Pi update:** replacement of the selected `core` image with an explicitly versioned build or an + immutable digest-pinned image. + +## New `thothctl pi restart` command + +### Interface + +```text +thothctl --installation pi restart --yes [--drain] +``` + +`--yes` is mandatory. Without `--drain`, the command refuses to proceed when active sessions +exist. With `--drain`, it closes new-session admission and waits until active sessions finish. +It never terminates active sessions merely because `--drain` was supplied. + +### Required behavior + +The command must: + +1. use the installation-aware Compose runner and durable current-image selector; +2. acquire the same exclusive lifecycle lock used by Pi update and rollback; +3. refuse to start when an interrupted update or restart requires recovery; +4. activate the durable maintenance gate before waiting for sessions; +5. validate the currently mounted Pi provider/model configuration before recreating `core`; +6. recreate only `core`, with `--no-deps`, `--force-recreate`, and a bounded health wait; +7. retain the exact currently selected image reference and never build or pull an image; +8. verify core health, bundled Pi version boundaries, mount/configuration identity, and the isolated + Pi/provider smoke after recreation; +9. clear maintenance and lifecycle state only after all verification succeeds; and +10. return sanitized, actionable failures without exposing credentials or raw configuration. + +If failure occurs before container mutation, the command clears maintenance and leaves the running +container untouched. If failure occurs after recreation, it leaves admission closed and records +recovery state. The operator repairs the reported host/Docker/configuration problem and uses the +documented maintenance recovery flow. The command must not silently claim success after a partial +restart. + +### Success output + +Success reports that the existing Pi image was retained, `core` was recreated, and readiness and +smoke checks passed. It does not print credentials or their contents. + +### Help and compatibility + +- `thothctl pi` usage text will list `restart --yes [--drain]`. +- Linux, macOS, and Windows builds expose identical command semantics. +- Existing `pi update`, `rollback`, `maintenance`, `doctor`, `test`, `logs`, and `configure` + behavior remains compatible. + +## Pi Management dialog redesign + +### Header instructions + +The update section begins with the exact short lead-in: + +> Using the host terminal: + +The existing Linux, macOS, and Windows tabs remain closed initially. Opening a tab shows an ordered +workflow made of short paragraphs, labels, lists, and code blocks rather than uninterrupted prose. + +Each tab contains: + +1. **Open the project root.** State that `deploy/` is directly in the ThothII project root, beside + `compose.yaml`. +2. **Edit the provider catalog.** Name the platform-appropriate path and explain the relevant + `models.json` fields in a compact definition list. +3. **Enable the model.** Name `deploy/pi/settings.json` and explain the `provider/model` values in + `enabledModels`. +4. **Set credentials.** Explain where to find `PI_AUTH_FILE`, what it points to, that the file stays + on the host, and how to protect it (`0600` on Linux/macOS, user-only ACL on Windows). Never show + real secret values. +5. **Reload configuration.** Show one platform-specific, directly executable `pi restart --yes + --drain` command using `~` for the user's home directory. +6. **Update the Pi version when needed.** Show one `pi update --version --source build + --yes --drain` command and explain that `` must be replaced with the desired pinned + version. Present digest-pinned `--source pull` as a clearly labelled advanced alternative, not + part of the normal path. +7. **Recover from an update failure.** Keep `pi maintenance status`, `pi logs`, `pi rollback --yes`, + and `pi maintenance recover --yes` in a compact secondary subsection. + +Linux and macOS use `~/bin/thothctl` and `~/thothii-installation.yaml`. Windows uses PowerShell, +`~\bin\thothctl-windows-amd64.exe`, and `~\thothii-installation.yaml` with `Resolve-Path` where +PowerShell requires expansion. + +### Application defaults + +The existing provider/model/reasoning form remains. Its description will say positively that it +selects defaults for new Pi work and stores no credentials. It will not tell the operator to run +`thothctl pi configure`; that command remains a terminal alternative documented outside the normal +GUI workflow. + +### Readiness, test, and diagnostics + +- Keep bundled Pi version, readiness sequence, **Save defaults**, and **Test saved defaults**. +- Keep the bounded sanitized diagnostics view. +- Rewrite descriptions into short, concrete sentences. Explain that diagnostics contain at most + 200 lines and omit declared secret values. + +### Removed UI + +- Remove “not this browser page”. +- Remove the duplicated bottom **Update Pi on the host** section. +- Remove the incomplete global `UPDATE_COMMAND` and its copy action. +- Remove the developer-only `:8080`/`:5173` and frontend rebuild note. +- Remove mandatory `pi configure`, explicit `stop`/`start`, and redundant post-update + `status`/`doctor`/`test` sequences from the platform tabs. +- Remove all native-Pi operator paths such as `~/.pi/agent/...` from the GUI. + +## Documentation changes + +- Update `docs/contracts/thothctl-pi.md` with the restart safety and recovery contract. +- Update `docs/install/pi-management.md` to separate GUI defaults, configuration reload, version + update, and failure recovery. +- Add a prominent ThothII-operator note to `docs/general/pi-configuration.md`: native Pi paths + describe container internals; operators edit `deploy/pi/...` and the host credential file. +- Update command/help verification scripts and any README command inventory that claims to list the + complete Pi lifecycle surface. + +## Testing + +### Go/CLI + +- Parser tests for required `--yes`, optional `--drain`, unknown flags, and extra arguments. +- Restart refuses active sessions without `--drain` and waits with it. +- Restart uses the durable current-image selector and recreates only `core` without build or pull. +- Pre-mutation validation failure leaves the container untouched and clears maintenance. +- Post-mutation verification failure leaves safe recovery state and maintenance active. +- Success verifies health/version/configuration/smoke and clears maintenance. +- Concurrent update/restart/rollback operations share the lifecycle lock. +- Output and failures remain sanitized on Linux and Windows paths. + +### Frontend + +- All platform tabs start closed. +- Each platform shows structured Docker-only instructions and its executable restart command. +- `PI_AUTH_FILE`, `models.json`, and `settings.json` are explained in operator language. +- No native-Pi paths, duplicated update section, incomplete copy command, or developer-only port + guidance remains. +- Existing save, test, readiness, scrolling, and diagnostics behavior remains covered. + +### Verification + +- Run all `tools/thothctl` Go tests and build the supported binaries. +- Run relevant documentation/command-contract scripts. +- Run the complete frontend test suite, TypeScript build, and production bundle build. +- Rebuild only the frontend service and verify the revised bundle and healthy service on port 8080. + +## Rollout and recovery + +The frontend change is independently deployable, but it must not advertise `pi restart` until the +corresponding `thothctl` binary has been built and made available to operators. Existing commands +remain unchanged. If deployment of the new binary is deferred, the GUI must retain the prior +supported stop/start fallback rather than display a nonexistent command.