okf-frontmatter

# okf-frontmatter OpenInvest's docs live in `docs/wiki/` (numbered chapters) and `docs/wiki/adr/` (decision records). Under **OKF** each doc starts with a YAML frontmatter block that is the *single source of truth* about that doc. Tooling reads the frontmatter; humans read the prose. The goal: stop maintaining huge prose docs that duplicate what the code already says — link to the code instead, and let `find_docs.py` do navigation. Point the script at a repo with `--repo <path>`, or just run it from inside that repo (it auto-detects the nearest ancestor containing `docs/wiki/`, else uses the working dir). It is read-only except for docs you explicitly edit. The conventions below use openInvest as the worked example, but the mechanics (`find` / `schema` / `lint`) work on any repo whose markdown carries OKF frontmatter. --- ## Job 1 — maintain docs the OKF way **The rule of thumb:** frontmatter is structured truth; prose is explanation. Anything that *is* a schema (a Pydantic model, a dataclass, a config key, an endpoint contract) lives in code — the doc **points** to it via `schema_source` / `documents`, it does not re-type it. When the code changes, `lint` tells you which doc's pointer went stale. Don't grow a doc past a few screens of "why / how it fits together"; if you're copying field tables out of code, stop and add a `schema_source` pointer instead. ### Frontmatter schema Common to every doc: | field | required | meaning | |---|---|---| | `type` | ✅ | `wiki-chap...