# 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.

```text
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

```bash
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.