Okf Frontmatter

---
name: okf-frontmatter
version: 0.3.0 # x-release-please-version
description: >-
  Maintain openInvest's docs (docs/wiki chapters + docs/wiki/adr) under Google's
  Open Knowledge Format (OKF). Two jobs. (1) Teach agents to maintain docs the OKF
  way — every doc carries a small YAML frontmatter block as the single source of
  truth (type, title, tags, intent, schema_source, documents); schema details link
  to the authoritative code instead of being copied into prose; no more
  hand-maintained thousand-line markdown. (2) Look docs up fast — grep the literal
  term FIRST; only when grep is ambiguous (hits scattered across files / synonym
  mismatch / zero hits) run find_docs.py to rank the owning doc by frontmatter
  intent, or resolve a doc's schema_source to the real code. Trigger phrases —
  "which doc covers X", "find the schema for PortfolioResponse", "where is
  GET /api/holdings documented", "docs for verdict.risk_profile", "add OKF
  frontmatter to this doc", "lint the wiki", "scaffold a new ADR/chapter".
  Run: scripts/run.sh find|schema|index|lint|new (or python3 scripts/find_docs.py
  --repo <path> ...).
---

# 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-chapter` \| `adr` \| `index` \| `reference` \| `report` \| `readme` |
| `title` | rec. | human title (usually the H1) |
| `tags` | opt. | `[api, rest, ...]` — coarse categories |
| `intent` | opt. | one short phrase the lookup ranks on, e.g. `API Contract`, `决策参数`, `部署` |
| `schema_source` | opt. | list of `relpath:Symbol` pointers to the authoritative code, e.g. `connectors/web_api/models.py:PortfolioResponse` |
| `documents` | opt. | `{endpoints: [GET /api/x], config_keys: [a.b], symbols: [Foo]}` — concrete things this doc covers |

ADR-only (lifecycle):

| field | meaning |
|---|---|
| `status` | `proposed` \| `accepted` \| `superseded` (normalizes the old `**状态**` line) |
| `date` | decision date |
| `supersedes` / `superseded_by` | ADR ids, e.g. `[010]` |

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
| command | use |
|---|---|
| `run.sh find <query>` | symbol (`PortfolioResponse`), endpoint (`GET /api/holdings`), config key (`verdict.risk_profile`), intent/tag, or keyword → ranked owning docs (JSON, strongest match first) |
| `run.sh schema <doc>` | resolve a doc's `schema_source` and print the real code definitions — read the authoritative schema without opening the prose |
| `run.sh index [--cache]` | dump the whole frontmatter index as JSON (`--cache` writes `docs/.okf-index.json`) |
| `run.sh lint [--ci]` | OKF compliance + drift; `--ci` exits non-zero only on errors (un-migrated docs are info, never a failure) |
| `run.sh new <type> <name>` | print a frontmatter skeleton |

---

## References
| file | when to read |
|---|---|
| `references/okf-spec.md` | what the Open Knowledge Format is (the 1-page version) |
| `references/conventions.md` | this repo's frontmatter schema + maintenance rules |
| `references/lookup-strategy.md` | the grep-first / script-fallback decision tree + benchmark |