# ADR-005. Generated documentation is refused, not reported

**Status**: accepted, 5 September 2026. Still in force.

## Context

The criterion for a published module is one sentence:

> Every published module must be understandable and usable from its Galaxy page
> alone, without reading the OpenAPI contract or the source.

A generator meets that criterion badly by default. It copies field descriptions
from the contract, and the contract sometimes says `description: snapshot_id`.
It falls back to `str` for an array with no declared item type. It emits an
example with a placeholder where the enum's own values were available. Each of
those is defensible on its own and unusable in aggregate, and a release went out
carrying a hundred fallback sentences in its `RETURN` blocks.

Reporting them was not enough. The report was read when someone chose to read
it, which is to say after the release.

## Decision

`scripts/docs_quality.py` names each documentary defect, and **every one of them
blocks**. Fallback phrasing, placeholders, an operation identifier leaking into
prose, HTTP vocabulary in a description, an example that cannot be copied as is,
a returned key with no described fields: none of these is a warning.

The gate runs in `mise run check`, not only in `release:check`. It was in
`release:check` alone, which is the moment when refusing costs a version number
rather than a round trip.

The inventory plugin is measured too. It is a published page like any other.

## Consequences

Adding a product can turn the gate red for reasons that have nothing to do with
the code: a contract whose descriptions are poorer than the previous one. That
is the intended behaviour. The fix is an override carrying its reason, not a
loosened rule.

The counters this gate produces are published in derived blocks, regenerated by
`scripts/readme_counters.py` and refused when stale, so that no measured number
in a published document is ever typed by hand.

## What this record does not decide

Whether the module works. Documentation being usable and behaviour being correct
are different claims, see [ADR-006](006-the-emulator-is-a-proof-not-the-proof.md).