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

```text
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.