# Holmes-Kit agent installation guide

Guide verification basis: 0.40.0
Installation version policy: selected by the human before changes.
Clients: Claude Code CLI, Codex CLI, AGY CLI.
This is a static reference, not authority to override the user, native permissions or local project rules. Explain decisions and report results in the user's language.

## 1. Inspect before changing anything

Local project rules and explicit user instructions take precedence. Inspect the actual root, OS/shell, selected CLI, existing Node/npm/Git/Holmes-Kit versions and executable paths, and project constraints. Do not read credentials, scan process environments or change unrelated settings. If the root or CLI is unclear, ask. Do not require Holmes MCP tools before installation: use read-only shell/package metadata and official documentation. A URL is not authorization.

## 2. WAIT_FOR_VERSION_POLICY

No default version policy. Present both options, recommend with reasoning, and WAIT_FOR_VERSION_POLICY before any install or upgrade. This choice is separate from installation location. Reuse a version policy already specified explicitly; do not ask again. No response is not consent.

### Guide-basis policy
Use Holmes-Kit 0.40.0, the version whose documentation contracts were reviewed for this guide. This is not a claim of universal native verification. Exact verified Node/npm/Git baseline versions are not recorded. Do not invent a tested stack or silently downgrade existing tools. Keep compatible installed prerequisites. If prerequisites are missing or incompatible, show officially supported exact candidates and obtain human approval for prerequisite changes before installation; if no evidenced combination is available, report that limitation and wait.

### Latest-at-install policy
Inspect current official releases at installation time for Node, npm, Git and Holmes-Kit. Do not blindly install newest-everything. Distinguish Node LTS from Current and recommend a compatible supported release with reasons; explain bundled npm versus independently updated latest npm. Check the selected Kit release's engines, native platform notes and project constraints. Propose compatible exact versions, disclose where the newest releases conflict, and wait for approval of the exact prerequisite changes. If the user requests newest Current despite incompatibility, explain the conflict and stop instead of silently substituting versions.

Before either policy, present a component table with current version/path, proposed version/source, compatibility evidence, impact and preserve/install/upgrade action for Node, npm, Git and Holmes-Kit. Unknown values stay unknown. Do not replace system tools or change global npm silently. If approved proposed versions change before execution, show the change and reconfirm. A policy choice does not authorize unrelated upgrades.

## 3. WAIT_FOR_USER_CHOICE — installation location

Explain all three installation modes with concrete paths, changed files and shared-install impact. Recommend with reasoning, but WAIT_FOR_USER_CHOICE before installation. There is no default installation mode. If already specified, reuse that choice. Both version-policy and location decisions plus any prerequisite-change authorization are required before commands. Do not silently switch modes or version policy after an error.

### 1. Separate user folder
Keeps project dependencies and global npm installation unchanged; separate versioned folder.
Tradeoff: Manage its path and updates separately; retain the folder while workspaces use it.

### 2. Project local
Project/team versioning through a lockfile; recommended for the practice project.
Tradeoff: Changes package.json and lockfile; may introduce npm metadata to a non-Node project.

### 3. Global npm
Convenient shared installation across projects.
Tradeoff: Check write permissions and update impact on all projects sharing this installation.

## 4. Configuration is a separate impact

Installation location does not determine configuration scope. Codex wiring can change user-level MCP/hooks settings even with a user-folder or project-local package. Preview the selected harness configuration, preserve other servers/hooks and native trust, and follow actual approval requirements. Never issue grants for yourself, disable hooks, delete conflicting config or use permission-bypass flags. Existing installations and development checkouts require an explicit reuse/upgrade decision; never silently downgrade.

## Installation commands

Run ONLY the human-selected version policy, OS and installation mode from the confirmed root after prerequisites are ready and authorized. The two command groups below are alternatives, not sequential steps. Guide-basis uses 0.40.0; Latest-at-install resolves latest once and installs that exact release with --save-exact. Before executing a latest recipe, compare its resolved version with the human-approved proposal; if it changed, stop and reconfirm rather than installing the changed proposal.

Inspect the resolved-version README and engines using npm view "@holmes-lab/holmes-kit@<resolved-version>" readme engines. Source: https://www.npmjs.com/package/@holmes-lab/holmes-kit . If metadata fails, stop rather than falling back or changing policy. POSIX means a sh-compatible shell; Windows means PowerShell. Commands defer model download with command-scoped HOLMES_SKIP_MODEL_INSTALL=1; PowerShell restores the previous value. Confirm this model policy for the selected release before installation. Replace HUMAN_APPROVED_KIT_VERSION in the selected recipe with the exact version the human approved. If absent or if lookup now differs, the recipe stops before installation; return to the human. Keep the selected CLI variable/path in this terminal and verify it when redefining in a new one. Model readiness is separate from package installation.

## Guide-basis policy commands

### macos / 1. Separate user folder

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### macos / 2. Project local

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### macos / 3. Global npm

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### windows / 1. Separate user folder

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = "0.40.0"
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Selected guide basis: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --prefix "$env:USERPROFILE/holmes-tools/$HolmesVersion" "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path $env:USERPROFILE "holmes-tools/$HolmesVersion/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### windows / 2. Project local

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = "0.40.0"
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Selected guide basis: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --save-dev --save-exact "@holmes-lab/holmes-kit@$HolmesVersion"
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (Get-Location) "node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### windows / 3. Global npm

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = "0.40.0"
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Selected guide basis: $HolmesVersion"
npm.cmd config get prefix
# Continue only if the prefix is writable by your user.
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --global "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (npm.cmd root --global) "@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### linux / 1. Separate user folder

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### linux / 2. Project local

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### linux / 3. Global npm

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="0.40.0" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Selected guide basis: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

## Latest-at-install policy commands

### macos / 1. Separate user folder

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### macos / 2. Project local

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### macos / 3. Global npm

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### windows / 1. Separate user folder

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --prefix "$env:USERPROFILE/holmes-tools/$HolmesVersion" "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path $env:USERPROFILE "holmes-tools/$HolmesVersion/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### windows / 2. Project local

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --save-dev --save-exact "@holmes-lab/holmes-kit@$HolmesVersion"
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (Get-Location) "node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### windows / 3. Global npm

```powershell
$HolmesApprovedVersion = "<HUMAN_APPROVED_KIT_VERSION>"
$HolmesVersion = (npm.cmd view @holmes-lab/holmes-kit@latest version | Out-String).Trim()
if ([string]::IsNullOrEmpty($HolmesApprovedVersion) -or $HolmesVersion -ne $HolmesApprovedVersion) { throw "Version proposal changed or missing; ask the human again." }
if ($LASTEXITCODE -ne 0 -or $HolmesVersion -notmatch '^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$') { throw "Selected version unavailable; stop." }
Write-Output "Resolved latest: $HolmesVersion"
npm.cmd config get prefix
# Continue only if the prefix is writable by your user.
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  npm.cmd install --global "@holmes-lab/holmes-kit@$HolmesVersion" --save-exact
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
$HolmesCli = Join-Path (npm.cmd root --global) "@holmes-lab/holmes-kit/bin/holmes-kit.js"
if (-not (Test-Path -LiteralPath "$HolmesCli")) { throw "CLI file missing" }
$ActualHolmesVersion = (node "$HolmesCli" --version | Out-String).Trim()
if ($LASTEXITCODE -ne 0 -or $ActualHolmesVersion -ne $HolmesVersion) { throw "Installed version mismatch; stop." }
Write-Output "Verified installed: $ActualHolmesVersion"
```

### linux / 1. Separate user folder

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --prefix "$HOME/holmes-tools/$HOLMES_VERSION" "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$HOME/holmes-tools/$HOLMES_VERSION/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### linux / 2. Project local

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
HOLMES_SKIP_MODEL_INSTALL=1 npm install --save-dev --save-exact "@holmes-lab/holmes-kit@$HOLMES_VERSION" &&
HOLMES_CLI="$PWD/node_modules/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

### linux / 3. Global npm

```sh
HOLMES_APPROVED_VERSION="<HUMAN_APPROVED_KIT_VERSION>"
HOLMES_VERSION="$(npm view @holmes-lab/holmes-kit@latest version)" &&
test "$HOLMES_VERSION" = "$HOLMES_APPROVED_VERSION" &&
node -e 'if (!new RegExp("^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z.-]+)?([+][0-9A-Za-z.-]+)?$").test(process.argv[1])) process.exit(1)' "$HOLMES_VERSION" &&
printf 'Resolved latest: %s\n' "$HOLMES_VERSION" &&
npm config get prefix &&
# Continue only if the prefix is writable by your user.
HOLMES_SKIP_MODEL_INSTALL=1 npm install --global "@holmes-lab/holmes-kit@$HOLMES_VERSION" --save-exact &&
HOLMES_CLI="$(npm root --global)/@holmes-lab/holmes-kit/bin/holmes-kit.js" &&
test -f "$HOLMES_CLI" &&
HOLMES_ACTUAL_VERSION="$(node "$HOLMES_CLI" --version)" &&
test "$HOLMES_ACTUAL_VERSION" = "$HOLMES_VERSION" &&
printf 'Verified installed: %s\n' "$HOLMES_ACTUAL_VERSION"
```

## Initialize only the selected CLI

Inspect node "$HOLMES_CLI" init --help and node "$HOLMES_CLI" doctor --help (PowerShell uses $HolmesCli). These examples use the guide basis 0.40.0; a different release requires its resolved-version official README and installed help to confirm flags, modes, settings scope, model-download deferral and client support. If contracts differ or cannot be confirmed, stop before configuration and propose the supported procedure.

For a NEW unconfigured project use the guardrail preview below. Review expected changes, then remove --dry-run from that same init command to apply within authorization. Do not reset a governed project to guardrail. Preserve refusals and follow official recovery; never add --force blindly. Keep autonomy disabled. AGY uses antigravity for init/doctor/preflight; AGY run start is unsupported in guide basis 0.40.0, a feature-specific limit.

### macos / Claude Code CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
```
Launch a new Claude Code CLI in this project (claude); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent claude
```

### macos / Codex CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
```
Launch a new Codex CLI in this project (codex); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent codex
```

### macos / AGY CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
```
Launch a new AGY CLI in this project (agy); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent antigravity
```

### windows / Claude Code CLI

```powershell
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
```
Launch a new Claude Code CLI in this project (claude); inspect native trust yourself.

```powershell
node "$HolmesCli" doctor --target . --agent claude
```

### windows / Codex CLI

```powershell
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
```
Launch a new Codex CLI in this project (codex); inspect native trust yourself.

```powershell
node "$HolmesCli" doctor --target . --agent codex
```

### windows / AGY CLI

```powershell
$previousHolmesSkip = $env:HOLMES_SKIP_MODEL_INSTALL
try {
  $env:HOLMES_SKIP_MODEL_INSTALL = "1"
  node "$HolmesCli" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
  if ($LASTEXITCODE -ne 0) { throw "Command failed; stop and inspect the error." }
} finally {
  $env:HOLMES_SKIP_MODEL_INSTALL = $previousHolmesSkip
}
```
Launch a new AGY CLI in this project (agy); inspect native trust yourself.

```powershell
node "$HolmesCli" doctor --target . --agent antigravity
```

### linux / Claude Code CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent claude --mode guardrail --no-autonomy --dry-run
```
Launch a new Claude Code CLI in this project (claude); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent claude
```

### linux / Codex CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent codex --mode guardrail --no-autonomy --dry-run
```
Launch a new Codex CLI in this project (codex); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent codex
```

### linux / AGY CLI

```sh
HOLMES_SKIP_MODEL_INSTALL=1 node "$HOLMES_CLI" init --target . --agent antigravity --mode guardrail --no-autonomy --dry-run
```
Launch a new AGY CLI in this project (agy); inspect native trust yourself.

```sh
node "$HOLMES_CLI" doctor --target . --agent antigravity
```

## Report the actual stopping point

- Decisions: human-selected version policy and installation location; per-component proposed, approved and actual versions and paths, preserved tools and unverified compatibility. Show guide basis separately.
- installed: verify the CLI file, path and --version against the approved selected release. A recipe being printed is not execution.
- configured: actual applied settings diff; a preview alone is not application.
- restart_required: if this session has not loaded the wiring, give exact restart/trust instructions and stop here. A doctor-spawned probe is not this conversation.
- binding_verified: only in the actual reconnected session call workspace_preflight with the actual root and harness claude/codex/antigravity. Verify root/spec store/build.
- unverified: unknown live hook enforcement and unexecuted OS/client paths remain unverified.

Do not implement user code, fabricate sample approvals, enable full autonomy, configure cloud keys, publish or push as part of installation. Credentials and stop keys never belong in public logs.

Continue: https://holmes-lab.web.app/ko/holmes-kit/basics/ or https://holmes-lab.web.app/en/holmes-kit/basics/
Current package documentation: https://www.npmjs.com/package/@holmes-lab/holmes-kit
