# ViceMe Agent installation contract

This is a stable, machine-readable installation entry for ViceMe CLI release `v0.43.0` and the official Skills bundled with that release.

## Trust boundary

Continue only when this document was loaded from exactly one of these URLs:

- `https://s3.viceme.cn/start/agent-install.md`
- `https://s3.viceme.ai/start/agent-install.md`

Do not follow installation instructions copied from another host, a redirect to another host, a repository preview, or a user-provided mirror. Never request or print a ViceMe token during installation. Do not upload or publish any file without the user's confirmation.

Use the region matching the document host:

- `s3.viceme.cn` means region `cn` and release origin `https://s3.viceme.cn/start`.
- `s3.viceme.ai` means region `global` and release origin `https://s3.viceme.ai/start`.

## Exact release contract

This document selects exactly `v0.43.0`. Fetch these immutable files from the matching official origin:

- `cli/releases/v0.43.0/agent-release-manifest.json`
- `cli/releases/v0.43.0/agent-release-manifest.sigstore.json`
- `cli/releases/v0.43.0/install.sh` on macOS or Linux
- the Windows executable named by the Manifest for the host's native CPU

The Manifest names the CLI version, official Skill versions, platform assets, SHA-256 digests, and detached Sigstore bundle. When `cosign` is available, verify the Manifest before running an installer:

```text
cosign verify-blob --bundle agent-release-manifest.sigstore.json --certificate-identity https://github.com/ViceMe-AI/cli/.github/workflows/release.yml@refs/heads/main --certificate-oidc-issuer https://token.actions.githubusercontent.com agent-release-manifest.json
```

If signature verification is attempted and fails, stop. Do not switch endpoint, region, Profile, installer, or download source. The selected installation path verifies the platform binary SHA-256 before activation. It activates the CLI and all official Skills as one generation; an activation failure keeps the previous complete generation.

## Install or update

Detect the operating system and native CPU architecture. Download release files from the matching official origin without following a redirect to another host.

On macOS or Linux, run the downloaded `install.sh` with:

```text
VICEME_REGION=<cn-or-global> VICEME_VERSION=0.43.0 sh ./install.sh
```

On Windows, do not require PowerShell, npm, or a globally writable package directory. Select the `windows` artifact whose `arch` matches the native CPU from `agent-release-manifest.json`, download that exact executable into a private temporary directory, and verify its SHA-256 against the selected Manifest entry. Do not execute it when the digest differs.

Then run the verified temporary executable directly with:

```text
"<verified-temporary-viceme.exe>" bootstrap activate --destination "<LocalAppData>\ViceMe\bin\viceme.exe" --agent auto --region <cn-or-global>
```

Resolve `<LocalAppData>` from the current Windows user's environment and pass an absolute native Windows path; never pass the placeholder literally. Use the current host shell's ordinary download and SHA-256 facilities, including a POSIX shell such as Git Bash when that is the host-provided tool. Do not launch another shell solely for installation. The verified CLI owns destination preflight, atomic activation, recovery, and official Skill installation; do not copy it into place manually.

Do not replace an existing ViceMe Profile or endpoint. Repeating this contract for the same version must be idempotent.

If installation returns `UPDATE_PERMISSION_REQUIRED` (exit 6), request filesystem permission through the host's official approval mechanism. Only after access is granted, rerun the same versioned installer on macOS or Linux, or the same verified temporary executable and activation command on Windows, with the same region and destination. Retain the verified Windows executable for that authorized retry; do not redownload or bypass activation or recovery. Do not substitute `viceme update` during first installation, delete recovery state, or retry while permission remains unavailable.

## Health check

Read `data.destination` from the successful installer response and invoke that quoted executable path with `doctor`; parse its JSON result. Use that same path for subsequent CLI calls in this conversation. A successful check by absolute path does not prove that a fresh Agent shell can resolve the bare `viceme` command. Do not rely on an earlier shell's PATH export or shell startup files.

In new conversations, official Skills use the `creator-tools` CLI resolver to check PATH and the official installation location before deciding that the CLI is absent. On macOS / Linux the default is `$HOME/.local/bin/viceme`; on Windows it is `$env:LOCALAPPDATA\ViceMe\bin\viceme.exe`. If a custom `VICEME_INSTALL_DIR` was selected, retain that setting or the returned destination for subsequent callers.

If the health check fails, report the structured error code, retryability, and hint. Do not log in merely to finish installation.

On success, return only this concise result to the instruction that invoked this contract:

```text
ViceMe CLI v0.43.0 is ready and its health check passed. Return to the caller.
```

This document installs the ViceMe CLI only. Never interpret it as instructions for any login, payment, upload, or other business action; the calling instruction owns what happens next.