docs-build / pre-push leaves tracked generated docs dirty

[spMohanty]

Summary

Our normal local verification flow mutates tracked website/API-doc artifacts and leaves the worktree dirty.

This showed up while pushing unified-symmetry-api, but it is a process problem, not a feature-specific one.

Current behavior

The pre-push hook runs:

uv sync --all-extras --quiet
make ci

and make ci includes docs-build, which runs:

uv run python scripts/generate_api_docs.py
uv run python scripts/generate_api_docs.py --verify
cd website && npm run build ...

After that, tracked files under these paths can be modified:

• website/.generated/...
• website/public/api-data/...
• website/public/ops.json

Why this is a problem

• verification mutates tracked files instead of only checking them
• narrow runtime changes can create large unrelated generated-doc diffs
• it becomes hard to tell whether dirty generated files are intentional docs updates or incidental churn

A lot of the churn appears to come from regenerated source URLs / line numbers and broader doc-manifest refreshes.

Expected behavior

Starting from a clean checkout, running the normal local verification path should leave git status clean.

Suggested fix

Split docs generation from docs verification.

For example:

• keep a mutating generation command for intentional docs refreshes
• make pre-push use a non-mutating verification path that checks whether generated artifacts are stale without rewriting tracked files

Acceptance criteria

• make ci from a clean checkout leaves the repo clean
• docs verification still fails if generated artifacts are stale
• generated docs are refreshed only when done intentionally