Getting started

Install

The gem runs on every Ruby since 2.4, which is older than anything a current OS ships, with exactly three runtime dependencies (rack, webrick, and minifts):

gem install okf
# or, inside a project
bundle add okf

Using Claude Code? The plugin installs the whole toolchain, skill and curation hook included, in two commands. Everywhere else, the gem is the way in.

No Ruby on the box? Run okf straight from the Docker image, the same CLI with nothing to install.

Point it at a directory

Any folder of Markdown files with YAML frontmatter is close to a bundle already. Check where it stands:

okf validate docs/

A conformant bundle exits 0. Errors mean one of three things is missing (parseable frontmatter, a non-empty type, or a reserved file that breaks its rules); the conformance model walks each one. Warnings never block you.

See the graph

okf server docs/

serving 37 concepts at http://127.0.0.1:8808 (Ctrl-C to stop)

Concepts render as nodes, plain Markdown links between them as edges. Click a node, read its Markdown, follow its backlinks. This is the same UI as the public demo, which serves the gem's own bundle.

Ask about quality

okf lint docs/

validate asks "is this legal OKF?"; lint asks "is it well curated?": orphans, missing concepts people link to, stubs, uncited claims. It is advisory by default and exits 0, so nothing breaks until you opt into gating with --fail-on warn. The curation model documents all sixteen checks.

Teach your agent

The gem ships the OKF agent skill, so a coding agent can author and maintain the bundle for you:

okf skill .claude     # Claude Code    -> .claude/skills/okf
okf skill .agents     # agent-agnostic -> .agents/skills/okf

Where next

• Your first bundle, a guided path from five files to a healthy graph.
• Bundle anatomy, what each file and field means.
• The CLI overview, every verb and the conventions they share.
• The OKF v0.1 spec, the format itself, exactly as shipped with the gem.