docs: design managed embedded pi operations

docs/superpowers/specs/2026-08-04-unified-compose-deployment-design.md

@@ -121,6 +121,62 @@ Upgrading Pi requires changing the pinned build argument, rebuilding the image,
 normal ThothII regression and image-smoke gates. The container health/smoke test verifies that Pi
 exists in the image and can be invoked without any host executable.
 
+## Pi management for non-technical operators
+
+Pi management uses a hybrid interface so an operator does not need Docker expertise while image
+updates remain reproducible and recoverable. Configuration and diagnostics are available in a
+ThothII “Pi Management” page; host lifecycle and upgrades are performed by a small ThothII control
+command named `thothctl`.
+
+The Pi Management page shows the bundled Pi version, runtime state, configured provider, default
+model and reasoning level, writable Pi-state location, and sanitized diagnostics. It supports
+editing non-secret installation defaults, selecting only supported values, validating free-form
+fields, testing provider credentials without displaying them, running a Pi smoke request, and
+viewing sanitized logs. Per-user model/reasoning preferences remain browser-local until an
+authentication system provides durable user identities; installation defaults and Pi runtime
+configuration are stored in the mounted ThothII settings/Pi volumes.
+
+The page may report that a newer supported Pi version exists, but it does not control Docker and
+does not mutate the package inside a running container. It presents the exact `thothctl pi update`
+command appropriate to the installation. On a loopback-only single-user installation, the normal
+configuration functions are available. On a server, privileged Pi management requires trusted
+upstream authentication/authorization; without it, privileged controls are disabled and host-side
+`thothctl` remains the only update path.
+
+`thothctl` provides the stable operator commands:
+
+```text
+thothctl status
+thothctl doctor
+thothctl logs
+thothctl update
+thothctl backup
+thothctl restore
+thothctl pi status
+thothctl pi doctor
+thothctl pi configure
+thothctl pi test
+thothctl pi update
+thothctl pi logs
+```
+
+The tool wraps validated Docker Compose operations and uses the same behavior on Windows, macOS,
+and Linux. Distribution may use a small native executable or platform launchers, but command names,
+prompts, exit codes, backups, and rollback semantics are identical. Interactive configuration asks
+plain-language questions, offers closed choices where possible, writes only local non-secret
+configuration, and directs credentials into protected secret files.
+
+`thothctl pi update` never runs `npm install` in the live container. It checks compatibility,
+records the current image/configuration, builds or pulls an image containing the selected pinned Pi
+version, recreates `core`, verifies health and `pi --version`, runs a smoke request, and rolls back
+to the recorded image if verification fails. The update preserves `/data` and `/home/thoth/.pi`
+volumes and prints a concise recovery result.
+
+For advanced support, documentation may expose `docker compose exec core pi ...`, but no browser
+shell is enabled by default. The `core` container never mounts the Docker socket. A future updater
+service or web-triggered image update requires a separate authenticated design and is outside this
+scope.
+
 ## Persistence
 
 Named volumes are the portable default for workstation installations. Server documentation shows
@@ -204,6 +260,10 @@ Two complete guides are maintained against the same architecture:
   and secrets, local image build or pinned image use, startup, health, upgrade, rollback, backup,
   and recovery.
 
+Both guides include a non-technical operator section for `thothctl`, Pi configuration, Pi upgrade,
+failed-upgrade rollback, and obtaining sanitized diagnostic output for support. Windows examples
+use native PowerShell commands or a packaged executable rather than assuming a Unix shell.
+
 Both guides use copy-pastable commands validated by scripts. They explain which configuration is
 shared in Git, which is installation-local, and how a server that only provides DWH/VectorDB is
 consumed without installing ThothII there.
@@ -214,8 +274,10 @@ Automated gates cover Compose rendering for local/server plus each Git transport
 Docker builds, container health, frontend-to-core same-origin routing, registry bootstrap and
 offline fallback, secret non-disclosure, and absence of PSD/Chirone/portal dependencies in active
 deployment files. Image tests also prove that the pinned Pi executable is available inside `core`
-and that no host Pi path is mounted or required. Existing backend, frontend, harness, registry, and
-installation-document tests remain required.
+and that no host Pi path or Docker socket is mounted or required. Contract tests cover every
+`thothctl pi` command, non-interactive exit codes, update rollback, volume preservation, secret
+redaction, and parity of Windows/macOS/Linux launchers. Existing backend, frontend, harness,
+registry, and installation-document tests remain required.
 
 Manual acceptance covers a clean macOS build, a clean Windows Docker Desktop/WSL2 build from a
 GitHub clone, a Linux server deployment behind a generic proxy, an update after `git pull`, volume
@@ -228,3 +290,4 @@ persistence, and restoration from backup.
 - Making PSD, Chirone, or `omics_portal` supported product profiles.
 - Synchronizing local filesystem sessions between installations without shared session storage.
 - Implementing persistent runtime SSH tunnels for workspace connectors in this migration.
+- Providing a browser terminal or allowing the application container to control the Docker daemon.