# Herdr Build Pitfalls

## Zig version: exact 0.15.2 required

Herdr vendors `libghostty-vt` which is compiled via `zig build` during
`cargo build`. The vendored library has an exact Zig version check.

**Wrong version → build error:**

```
error: Your Zig version v0.17.0-dev does not meet the required build version of v0.15.2

# Also breaks with:
error: invalid builtin function: '@cImport'          # removed in 0.17
error: member function expected 4 argument(s), found 3  # readFileAlloc changed
```

**Fix:** Download Zig 0.15.2 from ziglang.org, extract to `~/.local/`,
symlink `zig` into `~/.local/bin/`:

```bash
# Remove wrong version
rm -f ~/.local/bin/zig

# Download and install
wget https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz
tar -xf zig-linux-x86_64-0.15.2.tar.xz -C ~/.local/
ln -s ~/.local/zig-linux-x86_64-0.15.2/zig ~/.local/bin/zig

# Verify
zig version  # must print "0.15.2"
```

## Debian apt does not have Zig

`apt search zig` finds no matching package. Manual download from
ziglang.org is the only reliable path.

## `herdr --remote` requires interactive terminal for first install

The remote mode prompts for install confirmation via stdin. Running
non-interactively fails with:

```
Error: "matching remote herdr 0.6.2 is not installed at $HOME/.local/bin/herdr;
run from an interactive terminal to approve installation"
```

**Workarounds (pick one):**

1. Run from user's terminal:

   ```bash
   export PATH="/path/to/herdr/target/release:$PATH"
   herdr --remote <host>-ts-herdr
   ```

   Approve the prompt, TUI opens, quit with `q`.

2. Pre-install upstream binary on remote:

   ```bash
   ssh <host>-ts-herdr 'mkdir -p ~/.local/bin'
   ssh <host>-ts-herdr 'curl -L <release-url> -o ~/.local/bin/herdr && chmod +x ~/.local/bin/herdr'
   ```

   Then `herdr --remote` detects the existing binary and skips the prompt.

3. Use `HERDR_REMOTE_BINARY` env var to ship a local build:
   ```bash
   HERDR_REMOTE_BINARY=/path/to/herdr/target/release/herdr herdr --remote <host>-ts-herdr
   ```

## FreeBSD is not a supported remote platform

`RemotePlatform::from_uname()` in `remote.rs` only matches `"Linux"` and
`"Darwin"`. FreeBSD returns `"FreeBSD"` which causes:

```
Error: unsupported remote platform: FreeBSD amd64
```

Do not use `herdr --remote` against osa or any FreeBSD host.