ThothII/docs/superpowers/specs/2026-08-14-pi-management-operator-workflow-design.md

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

thothctl --installation <installation.yaml> 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 <VERSION> --source build --yes --drain command and explain that <VERSION> 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.