# Install and Verify Buildchain

Buildchain can be consumed as a standalone binary, an npm package, or a
repository workflow surface. In every case, verify the release record before
adopting a new version.

## Standalone Binary

Buildchain v4.0.0 does not publish standalone platform archives. This section
documents the verified legacy binary release contract; v4 consumers should use
the npm package or repository workflow surface below.

Use the archive that matches the platform:

| Platform | Asset |
| --- | --- |
| Linux x64 | `buildchain-x86_64-unknown-linux-gnu.tar.gz` |
| macOS arm64 | `buildchain-aarch64-apple-darwin.tar.gz` |
| Windows x64 | `buildchain-x86_64-pc-windows-msvc.zip` |

Linux example:

```bash
tag=v2.2.1
base="https://github.com/kungfu-systems/buildchain/releases/download/${tag}"
curl -LO "${base}/buildchain-x86_64-unknown-linux-gnu.tar.gz"
curl -LO "${base}/buildchain.release.json"
curl -LO "${base}/artifact-evidence.json"
npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
tar -xzf buildchain-x86_64-unknown-linux-gnu.tar.gz
./buildchain version
```

Windows example:

```powershell
$tag = "v2.2.1"
$base = "https://github.com/kungfu-systems/buildchain/releases/download/$tag"
Invoke-WebRequest "$base/buildchain-x86_64-pc-windows-msvc.zip" -OutFile buildchain.zip
Invoke-WebRequest "$base/buildchain.release.json" -OutFile buildchain.release.json
Invoke-WebRequest "$base/artifact-evidence.json" -OutFile artifact-evidence.json
npx @kungfu-tech/buildchain verify release-passport buildchain.release.json
Expand-Archive buildchain.zip -DestinationPath .
.\buildchain.exe version
```

The GitHub Release page does not publish loose top-level `buildchain` or
`buildchain.exe` files. The executable is inside each platform archive.

## npm Package

```bash
npm install -D @kungfu-tech/buildchain
npx buildchain version
npx buildchain doctor --json
```

The highest alpha minor publishes to the `alpha` npm dist-tag; older maintenance
minor alphas use `vX.Y-alpha` so they cannot roll the global alpha channel back.
Stable releases publish to
`latest`. Both are created by the protected Buildchain promotion transaction.

Stable consumers should pin the exact Buildchain version they have validated,
for example:

```bash
pnpm add -D @kungfu-tech/buildchain@4.0.0
```

If a repository dogfoods a just-published Buildchain version and pnpm's release
age policy blocks the install, use a temporary package/version-specific
`minimumReleaseAgeExclude` entry instead of weakening the registry policy for
all packages:

```yaml
minimumReleaseAgeExclude:
  - '@kungfu-tech/buildchain@4.0.0'
```

Remove that entry after the package is old enough for the repository's normal
policy. Do not use a broad exclude such as `@kungfu-tech/*` for this case.
Buildchain-managed Paper scaffold and migration commands maintain this exact
version entry in `pnpm-workspace.yaml` so an immediately published, verified
runtime can refresh the lockfile without weakening the policy for other
packages.

## Repository Integration

```bash
npx @kungfu-tech/buildchain init --type package --package-manager pnpm
npx @kungfu-tech/buildchain validate --require-version-state
npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0
```

Use `.buildchain/buildchain.toml` to declare lifecycle commands. The commands may use Node
package managers or non-Node tools such as pip, Conan, CMake, Make, or project
scripts.

## Verify a Release Passport

```bash
buildchain verify release-passport buildchain.release.json
buildchain explain release --passport buildchain.release.json --for agent --json
```

The verifier fails closed when the passport or its sibling evidence files are
missing required fields or mismatching artifact digests.