# 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:

```sh
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

```sh
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
```