Development setup¶

Tooling is managed with uv and nox.

uv sync --extra dev          # .venv with narratty and all dev tools
uv run pre-commit install    # ruff, mypy, codespell, commit-msg check

Quality gates¶

Command	What it runs
`nox`	Everything below (plus `format` locally; set `NOX_CI=1` to skip it)
`nox -s tests`	Unit tests on Python 3.12–3.14 with coverage
`nox -s lint`	`ruff check` + `ruff format --check`
`nox -s check_types`	mypy (strict settings in `mypy.ini`)
`nox -s necessary_imports`	fawltydeps: undeclared or unused dependencies
`nox -s dead_code`	vulture
`nox -s duplicates` / `cyclic_imports`	pylint R0801 / R0401
`nox -s performance`	Cold-start budgets for `--help` and shell completion
`nox -s docs`	`mkdocs build --strict`

Commits and PR titles follow Conventional Commits (feat: …, fix: …, docs: …). PRs are squash-merged, so the PR title becomes the commit.

docs/assets/ holds the logo files:

File	Use
`logo-source.svg`	Editable source (text as `<text>`)
`logo.svg`, `logo.png`	Full logo, text converted to paths (README, docs home)
`icon.svg`, `icon.png`	Square mark (docs header, avatars)
`favicon.ico`	Docs favicon (16, 32, 48 px)
`social-preview.png`	GitHub social preview (1280x640, set in the repository settings)

After editing logo-source.svg, convert the text to paths (JetBrains Mono NL ExtraBold, Bold for the output line) and re-export the PNGs.