Development

The complete one-time setup (tooling install, private registry tokens, git hooks) lives in CONTRIBUTING.md at the repo root. This page is the working loop.

The workflow

git checkout -b feat/your-feature

# code…

./run check          # lint + format + types + test — mirrors CI
./run check --fix    # auto-fix lint + format

git add .
git commit -m "feat: your message"
git push -u origin feat/your-feature

./run check runs exactly what CI runs, so green locally means green in CI. Prefer raw tools? They’re all there (uv run ruff check, uv run pytest, uv run mypy libs/) — but ./run check keeps you in check-mode, what CI enforces. Run it before every push.

Commit messages

We use Conventional Commits — they drive versioning and the changelog.

Type	Use for	Bumps
`feat`	New feature	minor
`fix`	Bug fix	patch
`perf`	Performance improvement	patch
`docs`	Documentation only	—
`refactor`	Code change (no feature/fix)	—
`test`	Tests only	—
`chore`	Maintenance	—

Breaking changes: add ! after the type → major bump.

Scope commits to a package (feat(core): …) — Release Please versions each libs/ member independently from the commits that touch it.

Changelog and releases

The changelog is generated from those commit messages — nobody edits it by hand:

CHANGELOG.md — every notable change, per version
Releases — tagged releases on GitHub

Working on these docs

The docs are a self-contained Astro/Starlight site in docs/ (its own package.json — nothing to install at the repo root).

./run docs --serve   # live-preview at http://localhost:4321
./run docs           # production build into docs/dist/

Pages live in docs/src/content/docs/ as Markdown/MDX with title and description frontmatter; the Guides and Reference sidebars autogenerate from their directories.

The API Reference is generated from the docstrings in libs/ — ./run docs regenerates it before every build, or run the generator directly:

uv run --with griffe python docs/scripts/gen_api_docs.py

Never edit the generated pages under docs/src/content/docs/reference/ (except index.md) — improve the docstrings instead.