lingtai-installation

# LingTai installation ## Normative contract Read the [Contract](https://lingtai.ai/help/reference/installation/CONTRACT.md) and paired [Anatomy](https://lingtai.ai/help/reference/installation/ANATOMY.md) before choosing or maintaining an entrypoint. The Contract fixes state classes, ownership, provenance, allowed writes, postconditions, and partial-failure meaning for this surface. If the contract, this guidance, an executable, or its tests disagree, stop and report the drift instead of inferring a more permissive operation. ## Ordinary install `https://lingtai.ai/install.sh` is the canonical ordinary official-install happy path. It installs one exact TUI release, verifies release provenance and the pinned kernel artifact, checks the selected target and runtime ownership, and writes metadata only after binary/runtime postconditions pass. ```sh curl -fsSL https://lingtai.ai/install.sh | bash ``` The ordinary path is first-install-only: it does **not** adopt, overwrite, or silently repair an existing target. It does **not** download, source, or execute this skill or any helper asset. `--version` must be an exact `vX.Y.Z` official release. `--from-source` only selects the source-build fallback for that exact official release; arbitrary `--ref` development work is handed off to `assets/dev.sh` with exit status 2. ## Explicit latest-main install Use the explicit opt-in when you want both current TUI `main` and current kernel `main`, with both full SHAs verified, recorded, and shown: ```sh curl -fsSL https://lingtai.ai/install.sh | bash -s -- --latest ``` `--latest` is a native mode inside this same mirrored `install.sh`: it resolves `refs/heads/main` in both `Lingtai-AI/lingtai` and `Lingtai-AI/lingtai-kernel` to full SHAs, verifies both checkouts against those pins, and builds/installs from them directly. There is no separate delegated download or handoff script. This is not the ordinary stable path and never falls back to it; arbitrary `--ref` work still belongs to `assets/dev.sh`. ## Native Windows install `https://lingtai.ai/install.ps1` is the canonical ordinary official-install happy path for native Windows (PowerShell 5.1 and PowerShell 7+). It parses and runs identically under both editions and is the PowerShell counterpart to `install.sh`: it resolves one exact TUI release, verifies the release's bundle manifest and archive checksum, verifies the staged `lingtai-tui.exe` reports the resolved version, and provisions the pinned managed Python runtime before writing any success metadata. ```powershell irm https://lingtai.ai/install.ps1 | iex ``` Like the POSIX path, ordinary install is first-install-only, never falls back to installing LingTai by package name, and only writes its receipt after binary and runtime postconditions pass. `-SkipVenv` remains the explicit TUI-only opt-out that omits the managed runtime and its receipt fields; it is not the default public path. WSL2 with `/install.sh` remains a supported alternative for users who prefer a Unix-like terminal on Windows. ## Removal `https://lingtai.ai/remove.sh` and `https://lingtai.ai/remove.ps1` fully remove an installation this receipt proves you own — nothing more: ```sh curl -fsSL https://lingtai.ai/remove.sh | bash -s -- --bin-dir "$BIN_DIR" --yes ``` ```powershell & ([scriptblock]::Create((irm https://lingtai.ai/remove.ps1))) -BinDir $BinDir -Yes ``` Both require an explicit bin directory and explicit consent; without `--yes`/ `-Yes` they print the exact planned deletions and delete nothing. The `lingtai.tui.install/v1` receipt is the only deletion oracle: removal deletes exactly the managed binaries, symlinks, and receipt-pointed runtime venv the receipt proves that directory owns, then deletes the receipt itself last. There is **no** filename-pattern sweep — a directory that merely looks like a runtime path but isn't the receipt's own `runtime_venv` is reported as a survivor, never deleted. Config, secrets, presets, and per-project state are never touched. A Homebrew-shaped target is refused, not partially removed. Running either script twice is safe: the second run reports nothing to remove. ## Choose an explicit asset Each asset is a standalone, directly fetchable CLI. Read its `--help`, supply absolute exact paths, review its plan, and provide its explicit authorization flag before mutation. Skill prose is not a safety mechanism. - **Healthy exact update** — [`assets/update.sh`](https://lingtai.ai/help/reference/installation/assets/update.sh). Requires an existing ordinary owned target, exact TUI archive and kernel artifact inputs plus their SHA-256 values, `--yes`, and an executable runtime launcher under the owned runtime root. A normal venv `bin/python` symlink is accepted only when its `sys.prefix` resolves to the selected physical venv; dev-source receipts are rejected. The pinned kernel input is copied to a recognized `.whl` filename before pip is called. Downloads, checksums, archive safety, unique-binary, exact identity, and receipt checks finish before mutation. Kernel/TUI/receipt phases are explicit and a failure reports possible partial changes; no rollback is claimed. - **Developer checkout** — [`assets/dev.sh`](https://lingtai.ai/help/reference/installation/assets/dev.sh). Requires explicit TUI/kernel checkout paths, an owned target, `--yes`, and declared source/runtime provenance. It builds editable development state only. After all postconditions it writes a complete `lingtai.tui.install/v1` receipt atomically, including canonical runtime/source paths, commits, and the observed kernel version. JSON is serialized by the selected runtime. - **Repair** — [`assets/fix.sh`](https://lingtai.ai/help/reference/installation/assets/fix.sh). Defaults to a read-only diagnosis. `--apply --yes` requires one explicitly named free runtime directory directly under the owned runtime root, binds the prior ordinary receipt/provenance, and creates no replacement over occupied state. It uses the required `python3` bootstrap only to parse the old receipt and create the new venv; a missing or broken old runtime is never executed. The pinned kernel input is passed to pip as a `.whl` path, and its observed `lingtai.__version__` must exactly match the prior receipt's `kernel_version` before the runtime pointer can change. A venv/install/postcondition failure names the possible partial directory and never claims deletion or rollback. - **Read-only receipt** — [`assets/verify.sh`](https://lingtai.ai/help/reference/installation/assets/verify.sh). Checks release and dev-source receipts structurally through the selected runtime. `sys.prefix` remains bound to the selected venv; ordinary imports must be physically inside it, while editable imports must be physically under the metadata-declared kernel source. TUI output must contain exactly one release identity token or standalone `dev`, matching the receipt; the observed `lingtai.__version__` must exactly match `kernel_version`. - **Full removal** — [`remove.sh`](https://lingtai.ai/remove.sh) / [`remove.ps1`](https://lingtai.ai/remove.ps1). Requires `--bin-dir`/`-BinDir` and `--yes`/`-Yes`. Deletes exactly the artifact set the receipt at that bin directory proves owned — managed binaries, owned symlinks, receipt-pointed runtime venv, then the receipt itself last — and nothing matched by filename pattern alone. Refuses a Homebrew-shaped target instead of partially removing it. Idempotent: a second run with no receipt present reports nothing to remove and exits 0. All mutating assets independently validate exact target ownership, metadata provenance, authorization, and postconditions. Assets do not call `refresh`, merge, release, deploy, or source `install.sh`/`install.ps1`/each other.