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
./run local          # run the app locally

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 src/) — 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.

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 sidebar is configured in docs/astro.config.mjs.

The API Reference is generated from the docstrings in src/ — ./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 in src/solutions_agents/ instead.