ThothII/docs/superpowers/specs/2026-08-14-thothctl-discovery-and-pi-update-design.md

Simplified thothctl installation selection and Pi update design

Decision

Keep every existing thothctl pi subcommand. Make the installation descriptor optional on the command line and resolve it automatically when the operator runs from the project tree. Keep --installation <path> as an explicit override for non-standard locations or multiple installations.

The normal Pi update becomes:

thothctl pi update

When --version is omitted, thothctl reads the single default ARG PI_VERSION=<version> from docker/core.Dockerfile in the selected installation's project directory and uses that pinned version with the existing transactional build/update path. An explicit --version <version> remains supported. The command does not fetch an arbitrary npm “latest”; the repository pin, lockfile, image labels, and executable must remain consistent.

Installation resolution

Resolution order is:

1. an explicit --installation <absolute-path>/thothii-installation.yaml;
2. THOTHII_INSTALLATION, when set to an absolute descriptor path;
3. automatic discovery from the current working directory and its parents.

Automatic discovery examines only the exact descriptor at each directory level and the immediate deploy/*/thothii-installation.yaml locations. It never recursively scans .artifacts, home directories, or unrelated descendants. A candidate must be a regular file and must pass config.Load. One valid candidate is selected. No candidates or multiple valid candidates produce an actionable error that names the expected locations and explains how to use --installation.

The resolver is shared by all existing top-level commands, not only pi, so thothctl status, start, stop, doctor, workspace, and the Pi commands have the same invocation rules. Existing explicit invocations remain valid.

Safety and compatibility

• No existing Pi subcommand is removed or renamed.
• Existing advanced pi update --source ... --image ... --yes --drain syntax remains accepted for compatibility.
• The short update path selects build mode and preserves the existing lifecycle lock, maintenance gate, session handling, candidate verification, image selector promotion, and rollback/recovery behavior.
• The default update uses the current checkout's declared Pi pin; changing to a newer Pi release still requires updating the repository pin and lockfile in the normal source-update workflow.
• Errors and automatic-discovery diagnostics never expose secret file contents.

User-facing examples

thothctl pi update
thothctl pi update --version 0.81.0
thothctl pi status
thothctl pi restart --yes --drain
thothctl --installation ~/operator/thothii-installation.yaml pi update