Fix wheel auto-detection and rework install to use symlinks (#2721)

* fix: resolve wheel auto-detection from executable path

Also pick the latest wheel when multiple versions exist in dist/
(filepath.Glob returns lexicographic order, so use last match).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: replace make install with mise run install using symlinks

Update development docs in CONTRIBUTING.md and README.md to document
all three build components (SDK, coglet, CLI) and their build order.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: document coglet linux wheel build and llms.txt regeneration in AGENTS.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: bfirsh

AGENTS.md

@@ -32,6 +32,7 @@ Development tasks are managed with [mise](https://mise.jdx.dev/). Run `mise task
 | `mise run build:cog` | Build cog CLI binary |
 | `mise run build:coglet` | Build coglet wheel (dev) |
 | `mise run build:sdk` | Build SDK wheel |
+| `mise run install` | Build and symlink cog to /usr/local/bin |
 
 ### Task Naming Convention
 
@@ -70,6 +71,10 @@ Tasks follow a consistent naming pattern:
 - `mise run build:coglet:wheel:linux-arm64` - Build for Linux ARM64
 - `mise run build:sdk` - Build SDK wheel
 
+**Install:**
+- `mise run install` - Symlink cog CLI to `/usr/local/bin` (requires `build:cog` first)
+- `PREFIX=/custom/path mise run install` - Symlink to custom location
+
 **Other:**
 - `mise run typecheck` - Type check all languages
 - `mise run generate` - Run code generation
@@ -123,7 +128,7 @@ The CLI code is in the `cmd/cog/` and `pkg/` directories. Support tooling is in
 The main commands for working on the CLI are:
 - `go run ./cmd/cog` - Runs the Cog CLI directly from source (requires wheel to be built first)
 - `mise run build:cog` - Builds the Cog CLI binary, embedding the Python wheel
-- `make install` - Builds and installs the Cog CLI binary to `/usr/local/bin`, or to a custom path with `make install PREFIX=/custom/path`
+- `mise run install` - Symlinks the built binary to `/usr/local/bin` (run `build:cog` first), or to a custom path with `PREFIX=/custom/path mise run install`
 - `mise run test:go` - Runs all Go unit tests
 - `go test ./pkg/...` - Runs tests directly with `go test`
 
@@ -144,7 +149,8 @@ The code is in the `crates/` directory:
 For detailed architecture documentation, see `crates/README.md` and `crates/coglet/README.md`.
 
 The main commands for working on Coglet are:
-- `mise run build:coglet` - Build and install coglet wheel for development
+- `mise run build:coglet` - Build and install coglet wheel for development (macOS, for local Rust/Python tests)
+- `mise run build:coglet:wheel:linux-x64` - Build Linux x86_64 wheel (required to test Rust changes in Docker containers via `cog predict`/`cog train`)
 - `mise run test:rust` - Run Rust unit tests
 - `mise run lint:rust` - Run clippy linter
 - `mise run fmt:rust:fix` - Format code
@@ -164,16 +170,19 @@ The integration test suite in `integration-tests/` tests the end-to-end function
 
 The integration tests require a built Cog binary, which defaults to the first `cog` in `PATH`. Run tests against a specific binary with the `COG_BINARY` environment variable:
 ```bash
-make install PREFIX=./cog
-COG_BINARY=./cog/cog mise run test:integration
+mise run build:cog
+COG_BINARY=dist/go/*/cog mise run test:integration
 ```
 
 ### Development Workflow
 1. Run `mise install` to set up the development environment
 2. Run `mise run build:sdk` after making changes to the `./python` directory
-3. Run `mise run fmt:fix` to format code
-4. Run `mise run lint` to check code quality
-5. Read the `./docs` directory and make sure the documentation is up to date
+3. Run `mise run build:coglet:wheel:linux-x64` after making changes to the `./crates` directory (needed for Docker testing)
+4. Run `mise run build:cog` to build the CLI (embeds the SDK wheel; picks up coglet wheel from `dist/`)
+5. Run `mise run fmt:fix` to format code
+6. Run `mise run lint` to check code quality
+7. Run `mise run docs:llm` to regenerate `docs/llms.txt` after changing `README.md` or any `docs/*.md` file
+8. Read the `./docs` directory and make sure the documentation is up to date
 
 ## Architecture
 

CONTRIBUTING.md

@@ -21,15 +21,33 @@ uv venv
 uv sync --all-groups
 ```
 
-### Common tasks
+### Building
+
+Cog is composed of three components that are built separately:
+
+- **Python SDK** (`python/cog/`) — the Python library that model authors use. Built into a wheel that gets installed inside containers.
+- **Coglet** (`crates/`) — a Rust prediction server that runs inside containers. Cross-compiled into a Linux wheel.
+- **Cog CLI** (`cmd/cog/`, `pkg/`) — the Go command-line tool. Embeds the SDK wheel and picks up the coglet wheel from `dist/`.
+
+```sh
+# Build everything and install
+mise run build:sdk                        # build the Python SDK wheel
+mise run build:coglet:wheel:linux-x64     # cross-compile the coglet wheel for Linux containers
+mise run build:cog                        # build the Go CLI (embeds SDK, picks up coglet from dist/)
+sudo mise run install                     # symlink the binary to /usr/local/bin
+```
+
+After making changes, rebuild only the component you changed and then `build:cog`:
 
 ```sh
-# Build cog binary
-mise run build:cog
+mise run build:sdk                        # after changing python/cog/
+mise run build:coglet:wheel:linux-x64     # after changing crates/
+mise run build:cog                        # after changing cmd/cog/ or pkg/, or to pick up new wheels
+```
 
-# Install cog to $GOPATH/bin
-make install PREFIX=$(go env GOPATH)
+### Common tasks
 
+```sh
 # Run all tests
 mise run test:go
 mise run test:python

Makefile

@@ -24,11 +24,7 @@ $(info └───────────────────────
 $(info )
 endif
 
-DESTDIR ?=
-PREFIX = /usr/local
-BINDIR = $(PREFIX)/bin
-
-INSTALL := install -m 0755
+PREFIX ?= /usr/local
 
 GO ?= go
 
@@ -50,8 +46,7 @@ wheel:
 
 .PHONY: install
 install: cog
-	$(INSTALL) -d $(DESTDIR)$(BINDIR)
-	$(INSTALL) cog $(DESTDIR)$(BINDIR)/cog
+	PREFIX=$(PREFIX) mise run install
 
 # =============================================================================
 # Test targets

README.md

@@ -156,13 +156,6 @@ sudo curl -o /usr/local/bin/cog -L "https://github.com/replicate/cog/releases/la
 sudo chmod +x /usr/local/bin/cog
 ```
 
-Alternatively, you can build Cog from source and install it with these commands:
-
-```console
-make
-sudo make install
-```
-
 Or if you are on docker:
 
 ```
@@ -179,6 +172,10 @@ brew upgrade cog
 
 Otherwise, you can upgrade to the latest version by running the same commands you used to install it.
 
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment and build from source.
+
 ## Next steps
 
 - [Get started with an example model](docs/getting-started.md)

docs/llms.txt

@@ -91,15 +91,20 @@ run = [
 ]
 
 [tasks.install]
-description = "Build and install cog CLI to /usr/local/bin (or PREFIX)"
-depends = ["build:cog"]
+description = "Symlink cog CLI to /usr/local/bin (or PREFIX). Run build:cog first."
 run = """
 #!/usr/bin/env bash
 set -e
 PREFIX="${PREFIX:-/usr/local}"
-install -d "$PREFIX/bin"
-install -m 0755 cog "$PREFIX/bin/cog"
-echo "Installed cog to $PREFIX/bin/cog"
+BINARY=$(ls dist/go/*/cog 2>/dev/null | head -1)
+if [ -z "$BINARY" ]; then
+    echo "Error: no cog binary found in dist/go/. Run 'mise run build:cog' first." >&2
+    exit 1
+fi
+BINARY="$(cd "$(dirname "$BINARY")" && pwd)/$(basename "$BINARY")"
+mkdir -p "$PREFIX/bin"
+ln -sf "$BINARY" "$PREFIX/bin/cog"
+echo "Installed $PREFIX/bin/cog -> $BINARY"
 """
 
 [tasks."build:cog"]

mise.toml

@@ -125,64 +125,103 @@ func getRepoRoot() (string, error) {
 	return strings.TrimSpace(string(out)), nil
 }
 
+// distFromExecutable returns the dist/ directory relative to the running cog
+// binary, if it appears to be in a goreleaser output layout (dist/go/<platform>/cog).
+// Returns empty string if the path cannot be determined.
+func distFromExecutable() string {
+	exePath, err := os.Executable()
+	if err != nil {
+		return ""
+	}
+	exePath, err = filepath.EvalSymlinks(exePath)
+	if err != nil {
+		return ""
+	}
+	// Binary is at dist/go/<platform>/cog → go up 2 levels to dist/
+	distDir := filepath.Clean(filepath.Join(filepath.Dir(exePath), "..", ".."))
+	if info, err := os.Stat(distDir); err == nil && info.IsDir() {
+		return distDir
+	}
+	return ""
+}
+
 // findWheelInDist looks for a wheel file matching the pattern in the dist/ directory.
 // Returns the absolute path to the wheel if found.
-// Checks multiple locations: ./dist, <repo-root>/dist
+// Checks multiple locations: ./dist, <repo-root>/dist, <executable-relative>/dist
 // If platformTag is non-empty, only wheels whose filename contains the tag are considered.
+// When multiple wheels match, the last one in lexicographic order is used (highest version).
 func findWheelInDist(pattern string, envVar string, platformTag string) (string, error) {
 	// First try ./dist in current directory
 	matches, _ := filepath.Glob(filepath.Join("dist", pattern))
 	matches = filterWheelsByPlatform(matches, platformTag)
 	if len(matches) > 0 {
-		absPath, err := filepath.Abs(matches[0])
+		best := matches[len(matches)-1]
+		absPath, err := filepath.Abs(best)
 		if err != nil {
-			return matches[0], nil
+			return best, nil
 		}
 		return absPath, nil
 	}
 
 	// Try repo root dist/
 	repoRoot, err := getRepoRoot()
-	if err != nil {
-		return "", err
+	if err == nil {
+		distDir := filepath.Join(repoRoot, "dist")
+		matches, _ = filepath.Glob(filepath.Join(distDir, pattern))
+		matches = filterWheelsByPlatform(matches, platformTag)
+		if len(matches) > 0 {
+			return matches[len(matches)-1], nil
+		}
 	}
 
-	distDir := filepath.Join(repoRoot, "dist")
-	matches, _ = filepath.Glob(filepath.Join(distDir, pattern))
-	matches = filterWheelsByPlatform(matches, platformTag)
-	if len(matches) > 0 {
-		return matches[0], nil
+	// Try dist/ relative to the cog executable
+	if distDir := distFromExecutable(); distDir != "" {
+		matches, _ = filepath.Glob(filepath.Join(distDir, pattern))
+		matches = filterWheelsByPlatform(matches, platformTag)
+		if len(matches) > 0 {
+			return matches[len(matches)-1], nil
+		}
 	}
 
-	return "", fmt.Errorf("%s=dist: no wheel matching '%s' found in %s\n\nTo build the wheel, run: mise run build:sdk (for cog) or mise run build:coglet (for coglet)", envVar, pattern, distDir)
+	return "", fmt.Errorf("%s=dist: no wheel matching '%s' found\n\nTo build the wheel, run: mise run build:sdk (for cog) or mise run build:coglet (for coglet)", envVar, pattern)
 }
 
 // findWheelInDistSilent is like findWheelInDist but returns empty string instead of error.
 // Used for auto-detection where missing wheel is not an error.
 // If platformTag is non-empty, only wheels whose filename contains the tag are considered.
+// When multiple wheels match, the last one in lexicographic order is used (highest version).
 func findWheelInDistSilent(pattern string, platformTag string) string {
 	// First try ./dist in current directory
 	matches, _ := filepath.Glob(filepath.Join("dist", pattern))
 	matches = filterWheelsByPlatform(matches, platformTag)
 	if len(matches) > 0 {
-		absPath, _ := filepath.Abs(matches[0])
+		best := matches[len(matches)-1]
+		absPath, _ := filepath.Abs(best)
 		if absPath != "" {
 			return absPath
 		}
-		return matches[0]
+		return best
 	}
 
 	// Try repo root dist/
 	repoRoot, err := getRepoRoot()
-	if err != nil {
-		return ""
+	if err == nil {
+		matches, _ = filepath.Glob(filepath.Join(repoRoot, "dist", pattern))
+		matches = filterWheelsByPlatform(matches, platformTag)
+		if len(matches) > 0 {
+			return matches[len(matches)-1]
+		}
 	}
 
-	matches, _ = filepath.Glob(filepath.Join(repoRoot, "dist", pattern))
-	matches = filterWheelsByPlatform(matches, platformTag)
-	if len(matches) > 0 {
-		return matches[0]
+	// Try dist/ relative to the cog executable
+	if distDir := distFromExecutable(); distDir != "" {
+		matches, _ = filepath.Glob(filepath.Join(distDir, pattern))
+		matches = filterWheelsByPlatform(matches, platformTag)
+		if len(matches) > 0 {
+			return matches[len(matches)-1]
+		}
 	}
+
 	return ""
 }