Development

Requires Go 1.26+. Run make help to list all available targets.

Common tasks

make build        # build the binary into ./bin
make run ARGS=... # run the CLI with arguments
make test         # run tests
make lint         # run golangci-lint
make fmt          # format the code
make ci           # tidy + vet + lint + race tests
make changelog    # regenerate CHANGELOG.md from git history

Local CI checklist

Before opening a pull request:

• make ci passes locally
• make docs-build passes (validates documentation)
• Pre-commit hooks installed (make pre-commit)

Documentation

Serve locallyBuild static site

Live reload at http://127.0.0.1:8000:

make docs-serve

Output is written to ./site:

make docs-build

The docs site uses MkDocs Material with Mermaid diagrams, admonitions, and git-based revision dates.

Tooling

This project uses pinned versions of the following tools:

Tool	Version	Purpose
GoReleaser	v2.16.0	Build and publish releases
git-cliff	v2.12.0	Changelog generation
golangci-lint	v2.12.2	Linting and formatting
pre-commit	4.6.0	Git hook management
MkDocs Material	9.6.14	Documentation site

Install the Go-based tooling and set up git hooks:

make tools        # install golangci-lint, goreleaser, and git-cliff
make pre-commit   # install and run pre-commit hooks

Community

• Contributing
• Code of Conduct
• Security policy
• Changelog

Releasing

See Releasing for the tag-based release workflow.