fix(ci): scope docs-deploy to the docs dependency group

[celefthe]

Problem

The Publish docs via GitHub Pages workflow (.github/workflows/deploy-docs.yml) has been failing on every push to main since at least 2025-10-17, including every release from v0.7.3 through v0.8.0 — 100% consistent, not flaky.

Root cause

The workflow runs uv run mkdocs gh-deploy --force --clean --verbose with no --group/--only-group flag. pyproject.toml defines dependency-groups.dev (bundling ci, docs, lint, test, types), and uv run resolves the dev group by default — not just the docs group the job actually needs.

The types group pulls in mypy[install-types, faster-cache, reports], whose reports extra depends on lxml. lxml==6.0.0 has no prebuilt wheel for the resolved Python version on ubuntu-latest, so uv falls back to building it from source, which fails:

Error: Please make sure the libxml2 and libxslt development packages are installed.

Fix

Scope the deploy step to only the docs dependency group, which is all mkdocs gh-deploy needs:

-        run: uv run mkdocs gh-deploy --force --clean --verbose
+        run: uv run --only-group docs mkdocs gh-deploy --force --clean --verbose

Verification

Ran uv run --only-group docs mkdocs --version locally in a clean venv: resolves and installs 36 packages with no lxml/mypy in the environment, confirming the types group (and its lxml build) is no longer pulled in.

Will confirm post-merge that the next push to main produces a green Publish docs via GitHub Pages run and that the Pages site updates accordingly.

🤖 Generated with Claude Code

[celefthe]

Thanks clanker