docs: design Pi restart operator workflow
This commit is contained in:
@@ -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 <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.
|
||||
Reference in New Issue
Block a user