Reference

Curation model

What well-curated means, made checkable.

The complementary question

okf validate asks "is this legal OKF?" and is forbidden by the spec from rejecting broken links or missing optional fields. okf lint asks the question that matters day to day: is this bundle navigable, complete, trustworthy? It reports over precisely the things validation tolerates, and it is advisory: exit 0 even with findings, unless you opt into --fail-on warn.

Six categories, sixteen checks

Filter with --only / --except using the individual check names (the parenthesized identifiers), not the category labels:

Category	What it catches	Checks
Reachability	concepts you cannot get to	`orphan`, `not_in_index`, `disconnected_component`, `unlinked`
Backlog	demand for concepts nobody wrote	`missing_concept`, `broken_index_entry`
Completeness	thin or unlabeled concepts	`stub`, `missing_title`, `missing_description`, `missing_timestamp`
Freshness	concepts older than a cutoff	`stale`
Provenance	claims without sources	`uncited_external`, `broken_citation`
Hygiene	link and title debris	`duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link`

Two knobs tune specific checks: --min-body N sets the stub threshold in characters (default 50), and --stale-after DUR sets the stale cutoff (90d, 12w, or an ISO date). Freshness is off until you ask for it: a plain okf lint never reports staleness.

Reading a report

OKF lint — docs
  concepts: 37   edges: 87   index.md: 10   log.md: 1
  hubs: features/chat/sources/source-ingestion-pipeline (×12), …

  Backlog
    · info  graph-view.md: referenced by 3 link(s) across 2 concept(s) but does not exist
  Hygiene
    ! warn  link-suggestions.md: reference-style link `[:approved_ids]` has no matching definition

  ⚠ 3 warn, 31 info

The hubs line names your most-linked concepts, the de facto entry points worth keeping excellent. The backlog findings are ranked by demand: a missing concept referenced from three places outranks one referenced once.

What lint deliberately does not compute

Two curation concerns need to understand meaning, not structure: contradictions between concepts, and semantic staleness (the code changed, the words did not). No deterministic check can decide those. okf lint --json is the structured substrate an agent consumes to reason about them, which is exactly how the agent skill divides the work: the CLI is the eyes, the agent is the judgment.

Gate it when you are ready

--fail-on warn turns warnings into exit code 1, which makes lint a CI gate instead of a report. The CI guide shows a working pipeline.