Install and first run

The judges' lab starts with make up. The runbook is LAB.md. The steps below are the Go build and the sample review without the lab.

The quick start: build Proven and run a first review with no network and no keys. Every command below was run on 22 October 2026 on a clean clone of main (16e269a), with Go 1.26.8 on macOS.

Prerequisites

Sample mode needs only Go.

Build

git clone https://github.com/saphan-ai/proven.git
cd proven
go build -o /tmp/proven ./cmd/proven

First review: sample mode

The trace is written to the user cache, in proven/logs, created so only that user can read it. PROVEN_LOG_DIR overrides that directory. A path that resolves inside the repository under review is refused when Proven loads.

mkdir -p /tmp/proven-run && cd /tmp/proven-run
/tmp/proven scan --sample "$OLDPWD/testdata/fixture/discount"

It prints three findings (F1 proved by a test, F2 and F4 by a query and its row), drops F3 for lack of evidence, and exits 0. The full output and what each line means: SAMPLE_MODE.md.

The container image

This needs Docker (with buildx) as well as Go. make image builds Proven's image for this machine. make image-check builds the binary and the image and checks that they print the same version line and the same sample review, then prints the image's size; it fails and names the first difference. The same check by hand, from the repository, after make build and make image:

cd "$(git rev-parse --show-toplevel)"
sh scripts/image-check.sh saphan/proven:latest ./bin/proven

In a git checkout the image must carry this checkout's commit as its org.opencontainers.image.revision label, or the check fails and names both commits; the binary is compared by its output only.

Inside the image the sample fixture is at /opt/proven/fixture/discount:

docker run --rm saphan/proven:latest scan --sample /opt/proven/fixture/discount

Before a live review: livecheck

A live review needs only a git repository.

From the repository:

go run ./cmd/livecheck

With nothing configured it names every service that is not ready, and why, and exits 1. An empty secret makes that service down and named, and the review continues; a wrong non-empty value is still refused, and an empty guardrail key refuses every model call unless the mode is off.

generator: not ready: nightshift: METERLESS_RUNTIME_TOKEN is empty
guardrail: not ready: guardrail: PROVEN_GUARDRAIL_KEY is empty
query: not ready: zetaris: ZETARIS_REST_URL is empty
container: not ready: prover: Prover off: container runtime "docker" not found: …
summary: 0 ready, 4 not ready

The Prover needs the test image on the host before a review; it never pulls one during a review. When livecheck says the image is not present, its line ends with the act to run, for example:

docker pull golang:1.26

Each setting it names, with its default: CONFIGURATION.md. A live review a judge can rerun, with one finding proved by a test and one by Zetaris: demo/live/README.md.

The command-line flags beyond scan --sample are documented by the shell's track.