okf-frontmatter

Your repo's Markdown docs (wiki chapters, ADRs, references) each start, under OKF, 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:

ADR-only (lifecycle):

Relationships between docs stay as ordinary markdown links in the body (that's the OKF
knowledge graph). supersedes/superseded_by are typed mirrors lint cross-checks.

Adding / changing a doc

• Scaffold: run.sh new <type> <name> prints a frontmatter skeleton to stdout — paste it
  at the top of the new file, fill it in.
• Fill schema_source/documents from the code the doc describes (grep
  connectors/web_api/models.py, core/schemas.py, core/config/).
• Run run.sh lint before committing — fix any error (broken link / dangling pointer /
  missing type).

See references/conventions.md for the full schema + the "no thousand-line prose" rule, and
references/okf-spec.md for what OKF is.

Job 2 — find the right doc fast (grep first, script as fallback)

find_docs.py is not the first move. grep is. The script only pays off when grep can't
tell you which doc is authoritative.

1. grep the literal term first (ripgrep) — zero script overhead.
2. grep is decisive? → read that doc, done.
   "decisive" = the term hits one file, or hits a heading / frontmatter (that doc owns it).
3. grep is ambiguous? → run.sh find <query>
   "ambiguous" = hits scattered across ≥3 files / only in prose / 0 hits (synonym mismatch).

Why: on a clean literal hit, grep is already optimal and the script just adds a call. The
win comes from not calling the script on easy queries — so don't run both in parallel.
The script's real value is matching intent, not strings: it ranks the doc whose
frontmatter owns the symbol/endpoint/config-key first, even when the literal keyword is
buried. Full decision tree + the benchmark behind it: references/lookup-strategy.md.

Commands

References