Compile Usage Docs From a Frozen Spec Hash, Not From Chat

Description and use

Usage docs are generated from a frozen spec snapshot, not from a chat, ensuring provenance and preventing stale or fabricated content.

Problem

Documentation generated from live chat transcripts can contain unverified claims and lack provenance, leading to inaccurate or misleading API usage pages.

Outcome

A reproducible, CI‑driven workflow that guarantees usage docs are tied to a specific spec snapshot, preventing stale or fabricated content from entering the documentation repository.

Workflow

• Freeze the OpenAPI spec and write its SHA‑256 hash to docs/SPEC.lock
• Run a CI check that compares the current spec hash to the lockfile
• If the hash matches, allow the generator to produce usage Markdown in docs/usage/
• If the hash mismatches, delete or block the generated docs and fail the PR
• Use scripts/classify_usage.py to scan generated docs for human‑owned phrases and reject them
• Place any non‑draftable content under docs/policy/ where the generator cannot write
• Merge the PR only after all checks pass and human review confirms policy compliance

Evidence

Usage pages stay honest when they compile from a frozen interface snapshot instead of from a chat transcript.

Source

Rows marked “Yes” should live under docs/usage/ and should be deleted automatically when the spec hash changes.

Source