| name | lingtai-update-diagnosis |
| description | Use when a TUI or portal install, update, build, or restart fails. |
| version | 1.0.0 |
| last_changed_at | 2026-07-18T00:00:00Z |
| maintenance | If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths. |
Failure diagnosis
Nested lingtai-update reference. Start with read-only identity checks:
lingtai-tui doctor
lingtai-tui version
command -v lingtai-tui lingtai-portal
If /update-tui says unknown, inspect the reported executable and the
TUI-owned ~/.lingtai-tui/install.json; do not substitute Homebrew. If a
source update fails, confirm its prefix/bin directory still exists and that the
requested tag is a strict vX.Y.Z release. If a Homebrew-to-native migration
fails, the reported failure line names the exact step (installer command,
install.json verification, binary version, or Python runtime) and confirms
the original Homebrew install is untouched and still usable; fix the reported
native-installer error, then retry with lingtai-tui self-update. Do not
substitute brew update or brew upgrade in this migration flow. The migration
step itself never uninstalls, unlinks, or deletes the Homebrew
formula/keg — do not suggest brew uninstall as part of recovering from a
migration failure; a failed migration has nothing to clean up. A successful
binary update still requires a fresh process: quit and relaunch the TUI.
If /update-tui or a startup prompt reports the native install as ready but
the migration as not complete, this is not a failure to diagnose: install.sh
and every artifact check succeeded, but the resolved lingtai-tui on PATH is
still the Homebrew one — typically because Homebrew's bin dir (for example
/opt/homebrew/bin on Apple Silicon) comes before install.sh's default native
bin dir on PATH. This state is expected to repeat on every subsequent
interactive launch until the human answers "y" to the concrete
"Remove the old Homebrew installation now? [y/N]" prompt (default No, so a
declined or non-interactive launch leaves it pending), or reorders PATH so the
native bin dir resolves first. self-update and doctor only ever report
this state and the manual brew uninstall lingtai-ai/lingtai/lingtai-tui
command — they never prompt or uninstall. It does not re-run the installer on
each detection.
For source-build failures, separate Go module fetches from the portal's
npm ci/frontend build. On asset download failure the installer is designed to
fall back to a source build; record the release tag, OS/architecture, and the
first actionable error rather than retrying blindly. Never paste environment
dumps, tokens, or private paths into reports. Python import, venv, or kernel
errors are outside this skill; follow the kernel's system-manual
runtime/kernel update manual.
