Okf

Open Knowledge Format (OKF)

You are the OKF expert in this repository. OKF is knowledge as code: a directory of markdown files, each with YAML frontmatter, that both humans and agents read from the same source. It is minimal on purpose — no schema registry, no runtime, no SDK. All the power lives in conventions and judgment, not in enforcement. This skill is where that judgment lives; the okf CLI handles the mechanics.

Two ideas govern everything:

• Dual audience. Every file must serve a human skimming it and an agent extracting from it. That is why bodies are structural markdown and links are plain markdown links — both readers already understand them.
• The graph is emergent. Files are nodes, markdown links are edges. You never declare a graph; it arises from how you link concepts. Good linking is good knowledge modelling.

The hard rules (§11 conformance)

Three conditions, all hard — validate fails a bundle on any of them:

1. §11 cond. 1 every non-reserved .md file has a parseable YAML frontmatter block;
2. §11 cond. 2 every such block has a non-empty type;
3. §11 cond. 3 every reserved file present is well-formed — a nested index.md has no frontmatter, the bundle-root index.md carries only okf_version, and log.md date headings are ISO YYYY-MM-DD.

Everything else is soft guidance, and consumers MUST tolerate missing optional fields, unknown types, and broken links — a bundle is never rejected over them.

Three lenses — hold them separate

Judging a bundle means asking three different questions. Conflating them is the most common mistake:

validate is forbidden by §11 from failing a bundle for broken links or missing optional fields — that is lint's job. And neither tool can judge contradictions or semantic staleness (a concept that parses fine but no longer matches reality); only an agent reasoning over meaning can. That last lens is where you earn your keep as the expert, not the executable.

The CLI is your eyes — you are the judgment

The okf executable answers every mechanical question deterministically, and its read views show everything the browser UI does. Don't probe for it — just run the verb. A proactive command -v okf before every task spends a whole tool round proving what the next command reveals for free; the CLI's own failure is a cheaper, truer signal. (The two deliberate exceptions are menu and doctor — both decide whether to install, so they check first.) The one distinction to hold: a shell okf: command not found is the only thing that means "install it" (→ doctor); every line that starts error: is okf answering — a bundle or usage result to read and act on, never a missing toolchain to send to doctor.

Don't memorize the surface — okf --help maps every verb, okf <verb> --help its flags. The division of labour is the whole game:

• Shell out — never eyeball — anything a verb computes: conformance (§11), what exists, what links where, where a term lives, what's stale, the map. Every read verb takes --json and the list views filter by type/dir/tag, so ask the narrow question instead of paging the bundle.
• Skeleton first, bodies last. dirs, search, graph --minimal, and --fields projections each answer for a fraction of a dump's bytes; full bodies are the final step of a retrieval, never the first. <!-- rule:okf-skeleton-first -->
• You judge — the CLI can't — meaning: contradictions, semantic staleness (parses fine, no longer true), whether a loose file is terminal-by-design, whether a singleton tag is a deliberate marker. Tool output is evidence, never a verdict.

The one trap worth carrying in your head: the age cutoff is off by default — a plain okf lint reports concepts past their own declared stale_after (the expired check reads the clock the CLI supplies), but never judges age; pass --stale-after <90d|12w|ISO-date> when you want anything not touched since then flagged too — the two mechanisms share a spelling and nothing else (cli/checks.md, rule okf-two-clocks).

<!-- check:stale -->

Read cli.md before interpreting a verb's output in depth. It is the index and the shared contract — refs, exit codes, --json, the filters — and its table routes to the one file the verb lives in: checks (what validate may and may not reject, lint's categories and check ids), search, map (index/dirs), views (the tag-curation views), serve (the trust boundary), registry, graph.

Orient before you touch anything

Picking up a bundle you don't already know — to consume or maintain — start with okf dirs <dir|@slug>: one row per directory, so it stays small on a bundle of any size and it names the branches every other view narrows to. Then open the one you want with okf index <dir|@slug> --dir <branch> (the §8 map: that directory's index body, rollups, and listing), and read log.md (the §9 baseline of what changed last) — all of it before greping or opening leaves. Reach for index rather than grep for the one reason that outranks convenience: grep cannot find an index entry that is missing, so enumeration drift is invisible to it — you can't search for the word that should be there but isn't. <!-- rule:okf-orient-index --> Per-verb steps are in the playbooks (the Commands table below; no okf installed? read the root index.md plus each area's index.md).