/okf

name: okf
description: >-
  Be the expert on Open Knowledge Format (OKF) — portable project knowledge as a
  directory of markdown files with YAML frontmatter that humans and agents read
  from one source. Use when capturing knowledge into a bundle (a service, schema,
  metric, decision, runbook: "document this in OKF", "capture this as a concept"),
  converting existing docs into one ("migrate/OKFy our docs into a bundle"),
  retrieving from one without reading it whole ("what do we know about X?", "where
  is X documented?", "search the bundle"), updating one after code or docs
  change ("update the knowledge bundle"), checking its conformance or curation
  quality ("validate/lint the bundle"), serving or rendering it as a graph, or
  working in a repo that already carries an OKF bundle — a `.okf/` directory or a
  root `index.md` carrying `okf_version`.
user-invocable: true
argument-hint: "[search|produce|migrate|maintain|refine|consume|curate|doctor|<okf-cli-verb>] [dir|@slug] [--flags]"
allowed-tools: Read Write Edit Grep Glob Bash

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:

| Lens | Question | Tool | Nature | |-----------|-----------------------------------|-------------------------|---------------------------| | **Legal** | Is it conformant OKF? (§11) | `validate` | Binary, tolerant | | **Good** | Is it navigable, complete, fresh? | `lint` | Advisory, structural | | **True** | Is it consistent and *current*? | *you*, over `lint --json` | Semantic — needs meaning |

`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](playbooks/menu.md) and [doctor](playbooks/doctor.md) — 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](playbooks/doctor.md)); 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](reference/cli/checks.md), rule `okf-two-clocks`). <!-- check:stale -->

Read [cli.md](reference/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