# Unified `tht` CLI and Product Setup Design

Date: 2026-08-15

## Objective

Turn the repository into a product that can be cloned, bootstrapped once, and then operated with a
single normal system command named `tht`. The operator must not build Go manually, create a `bin`
directory, remember an installation descriptor path, or use raw Docker commands for normal
installation, lifecycle, Pi updates, backup, or restore.

## Confirmed decisions

1. The only product command name is `tht`.
2. `thothctl` is removed completely. There is no compatibility alias, wrapper, deprecation period,
   or second installed command.
3. The host operator implementation remains a native Go binary so macOS, Linux, and Windows hosts
   do not require Go, Python, or a virtualenv.
4. The existing Python workflow CLI remains inside `core` under the same command name `tht`.
   Backend and Pi continue to use it there. It is not installed on the host and is not presented in
   operator documentation. No `tht-runtime` command or namespace is introduced.
5. The command audit is binding: 55 commands are `MAINTAIN`, 8 are `ENHANCE`, and 14 are `ERASE`.
   The detailed decision matrix is in
   `docs/reports/2026-08-15-tht-command-maintain-erase-enhance.md`.
6. Workflow commands called by Pi, the gate, the backend, workspace maintenance, or the session
   migrator are machine contracts. Their semantics, pristine JSON output, stdin behavior, and exit
   codes are not changed merely to simplify the operator help.
7. The public operator help stays small. Internal workflow commands do not appear in host help.
8. `--installation` remains available as an optional override. Normal commands discover the
   installation from the current project root or worktree.
9. `backup` and `restore` are introduced as first-class product commands.
10. The final implementation is installed on this Mac and used to rebuild/restart the live stack on
    port 8080.

## Command boundary

### Host operator CLI

The native host command exposes:

```text
tht setup
tht version
tht start [--build]
tht stop
tht status
tht doctor [--json]
tht logs
tht update [--check-only] [--yes] [--drain]
tht backup [--output PATH] [--include-secrets --yes] [--drain]
tht restore ARCHIVE --yes [--drain]
tht sessions migrate --yes
tht remove [--yes ID...]
tht pi ...
tht workspace ...
```

`tht pi` preserves `status`, `doctor`, `test`/`check`, `configure`, `restart`, `update`,
`rollback`, `maintenance`, and `logs`. `tht workspace` preserves every currently implemented
workspace operation, including the two vector operations missing from the current help.

### Container workflow CLI

The Python command tree remains the deterministic protocol used by Pi and the backend. The host
installation does not expose these commands as operator shortcuts. This prevents a human operator
from bypassing reviewer gates while avoiding a risky rewrite of the live workflow.

The `MAINTAIN`, `ENHANCE`, and `ERASE` decisions apply exactly as recorded in the command audit.
`MAINTAIN` commands retain their current path. `ENHANCE` commands receive the approved safety or
diagnostic improvements. `ERASE` commands disappear from Typer registration and active docs; domain
functions still used by canonical pipelines remain internal libraries.

## Bootstrap and PATH installation

A freshly cloned repository necessarily needs one bootstrap action before `tht` exists:

```bash
bash scripts/install-tht.sh
```

Windows uses:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/install-tht.ps1
```

The scripts require Docker, build the correct native binary using the repository-pinned Docker
builder, verify it, and install it atomically:

- macOS and Linux: `/usr/local/bin/tht`, requesting elevation only for the final atomic install;
- Windows: `%LOCALAPPDATA%\ThothII\bin\tht.exe`, adding that directory to the user PATH when needed.

The user never selects a platform binary, runs Go, creates a `bin` directory, or invokes a
project-relative executable. Re-running the installer upgrades the installed command idempotently.

## Project and worktree discovery

Every host command starts from the current working directory and walks parents until it finds the
ThothII root contract (`compose.yaml`, `deploy/`, and the repository marker). A Git worktree root is
treated exactly like the main checkout.

Installation resolution order is:

1. explicit `--installation PATH`;
2. `THOTHII_INSTALLATION`;
3. one valid `thothii-installation.yaml` in the current directory or immediate `deploy/*`;
4. the same search while walking parent directories.

Zero candidates produce a setup-oriented error. Multiple candidates produce a bounded list and
require `--installation`; no arbitrary recursive search is allowed.

## `tht setup`

`tht setup` is idempotent and defaults to the local profile on macOS, Windows, and workstation
Linux. `--profile server` selects server behavior. Generated installation files live under
`deploy/<installation-id>/`, where `deploy` is explicitly documented as a directory in the project
or worktree root.

The setup flow:

1. verifies root/worktree identity, Docker, Compose, supported architecture, and line endings;
2. creates or validates the installation descriptor and non-secret environment files;
3. asks plain-language questions and stores secret file paths, never secret values in the
   descriptor;
4. creates protected secret-file templates only after explicit confirmation and never overwrites an
   existing file;
5. renders and validates Compose configuration;
6. builds the ThothII images from the current checkout;
7. starts the stack with `docker compose up --detach --remove-orphans`;
8. waits for bounded health checks;
9. runs installation diagnostics and Pi diagnostics;
10. prints the URL and the exact descriptor selected.

`tht setup --configure-only` stops after validated configuration. `tht setup` never silently
replaces a descriptor, environment file, secret file, or generated state belonging to another
installation.

## Lifecycle and product update

- `tht start` starts the selected installation without rebuilding.
- `tht start --build` builds current-checkout images before startup.
- `tht stop` stops the installation while preserving state.
- `tht update --check-only` retains its current non-mutating validation behavior.
- `tht update` becomes the complete product update: lifecycle lock, active-session check/drain,
  backup checkpoint, image build from the current checkout, controlled recreation, health checks,
  diagnostics, and rollback to the recorded images when verification fails.

Product update and Pi update remain separate. `tht update` updates ThothII. `tht pi update` updates
only Pi in `core`.

## Pi management

`tht pi update [--version VERSION]` makes the version optional. Without `--version`, it queries the
latest stable version of the pinned Pi package from the authoritative package registry. A lookup
failure stops before mutation and tells the operator to retry or supply `--version`; it never
silently substitutes an older pin.

The command builds or pulls a candidate, verifies the Pi executable, `PI_VERSION`, and image label,
recreates only `core`, checks health, runs the smoke test, preserves volumes, and rolls back on
failure. Interactive terminals receive one clear confirmation; non-interactive execution requires
`--yes`. Model/provider selection remains the responsibility of `tht pi configure` and is not a
required argument to Pi update.

The project release pin in `docker/core.Dockerfile` remains the clean-build default. Installation
update state records the selected newer image/version so ordinary restart does not revert it.

## Backup and restore

`tht backup` creates a versioned manifest and checksummed archive in
`~/.thothii/backups/<installation-id>/` unless `--output` is supplied. It acquires the lifecycle
lock, refuses active work unless `--drain` is accepted, obtains a consistent stopped snapshot, and
restarts/verifies a previously running installation.

The backup includes:

- installation descriptor, non-secret environment/configuration, generated overrides, and source
  revision metadata;
- installation-owned settings, Pi state, workspace registry, workspace secrets volume, sessions,
  Qdrant data, and embedding-model volume;
- server bind roots returned by the installation preservation contract;
- a manifest of external secret-file paths and digests.

Secret-file contents are excluded by default. `--include-secrets --yes` includes them and marks the
archive sensitive; the file is created with owner-only permissions. A backup without secrets is
restorable only when all referenced secret files still exist and match preflight requirements.

`tht restore ARCHIVE --yes` validates schema version, checksums, installation identity, target
ownership, secret prerequisites, disk space, and stopped/quiescent state before mutation. It creates
a rollback checkpoint, restores only manifest-listed paths/volumes, starts the stack when it was
previously running, and runs health, `doctor`, `pi doctor`, and workspace inspection. Failure keeps
the target in a recoverable stopped state and prints the checkpoint path.

## Pi Management frontend

The frontend uses only Docker-based instructions and only the command `tht`. The section:

- begins fully collapsed;
- uses separate Linux, macOS, and Windows environment panels, with none open initially;
- is shorter than the current panel and has a working vertical scrollbar;
- begins with the exact concise wording `Using the host terminal`;
- explains that `deploy` is a directory in the project/worktree root beside `compose.yaml`;
- explains that `deploy/pi/models.json` and `deploy/pi/settings.json` are host files mounted
  read-only into `core`, so the operator edits the host files, not files inside the container;
- explains credential-file concepts in plain language rather than presenting environment-variable
  names without context;
- shows direct commands such as `tht pi configure`, `tht pi restart`, `tht pi update`,
  `tht pi status`, `tht pi doctor`, and `tht pi test`;
- contains no Go build, `~/bin`, `./bin`, `./tht`, `thothctl`, or mandatory descriptor path.

The sanitized-log control must either display the bounded, sanitized `core` log response or fail
with a visible error. The live model selector must reflect the mounted Pi configuration, including
the existing GLM 5.3 change after `core` is recreated.

## Documentation

Active user, installation, architecture, CLI-contract, testing, and README documentation is
rewritten around the bootstrap-plus-setup flow and the direct `tht` command. Historical
`docs/superpowers` plans/specs remain historical records; the new spec supersedes them.

Documentation examples run from the project/worktree root, refer to the home directory as `~`, and
do not teach manual Go builds or manually constructed installation paths for normal use. Advanced
sections may document optional `--installation` and non-interactive flags.

## Safety and acceptance

- Existing user changes to `deploy/pi/models.json` and `deploy/pi/settings.json` are preserved.
- Unrelated dirty-worktree files are not overwritten or committed accidentally.
- JSON contracts remain pristine and secrets are sanitized from stdout, stderr, logs, archives, and
  failure messages.
- Tests cover macOS/Linux shell installation, Windows PowerShell installation, root/worktree
  discovery, setup idempotency, lifecycle rollback, Pi latest-version lookup, command audit,
  backup/restore, frontend layout/copy, and active-document command examples.
- Final acceptance installs `tht` on this Mac, verifies `command -v tht`, confirms `thothctl` is
  absent, updates the live stack, checks healthy services, opens port 8080, verifies Pi Management,
  and confirms GLM 5.3 is selectable.