How these docs are built

Documentation that is written by hand drifts from the software it describes, and the drift is invisible until somebody follows an instruction that no longer works. Everything under API Reference and CLI Reference is therefore generated, and CI fails when the generated output stops matching the source.

The three sources

Section	Generated from	Who produces it
API Reference	`contracts/openapi/v1.json`	the API, exported on merge and hash-locked in `.generated-files.lock`
CLI Reference	`cli._parser.build_parser()`	the same argparse tree the installed binary builds
Guides	`docs/marketplace/*.md`	written by hand, the only prose here

How the two references are cross-linked

The link between a command and the endpoint it calls is derived, not declared. A hand-maintained table would rot the first time a handler moved; this chain breaks loudly instead.

operationId
  │  logion.v1._operation_map.IMPLEMENTED_OPERATIONS
  ▼
client.v1.<resource>.<method>
  │  AST scan of the handler each argparse leaf registers
  ▼
logion <command>

Each argparse leaf carries set_defaults(handler=…), so the generator resolves a command to a real function, parses that function, and collects the SDK calls it makes. Reversing the operation map turns those into operation ids.

Staleness is a build failure

make docs-generate        # rewrite the artifact
uv run python scripts/gen_docs.py --check   # what CI runs

The check recomputes the artifact and compares it byte for byte. A contract sync that adds an endpoint, or a new CLI flag, turns the build red until the docs are regenerated — which is the only thing that makes “the docs are current” a fact rather than a hope.

What is not generated

The guides are prose and stay prose. Generated reference tells you what exists; it cannot tell you why, or which of two endpoints you want. Both are needed and neither substitutes for the other.