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:

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