GUIDES
Short, hand-written orientation. Four pages, read in order or jumped into.
| Guide | Answers |
|---|---|
| Overview | What PaveDB is, and the four nouns everything is built from |
| Components | Server, CLI, clients — which one you should be using |
| Basic operations | Create, ingest, search, inspect, replay |
| Running it | Auth, the data directory, health checks, containers |
How the documentation is split
Four sources, and they do not overlap by accident:
| Source | What it is | When it changes |
|---|---|---|
| These guides | Hand-written orientation. Deliberately short. | When the mental model changes |
docs/reference/ | Generated from the code: every config key, every command, every protocol. | Every release, automatically |
openapi.json | The wire contract: every endpoint, request and response. | Every release, automatically |
| The PaveDB book | Long-form: why it works this way, and the hard parts. | Independently |
The references are generated, so they are exhaustive and never drift. These guides are not exhaustive on purpose — if a page here starts listing flags, it is doing the reference’s job badly. The book goes deep; these pages get you oriented in a few minutes.
If you want to change PaveDB itself rather than use it, you want
CONTRIBUTING.md, not this directory.