okf-gem

okf-gem (okf on RubyGems) is the complete harness for Open Knowledge Format (OKF) v0.1 bundles: create, maintain, and consume your project's knowledge with your agent. The package is Agent Skill + CLI/Lib + Graph: an agent skill that authors and curates, a CLI and Ruby library that validate, lint, search, and embed, and a graph to explore, live or static, in one gem that runs 100% local. A bundle is a directory of Markdown files with YAML frontmatter that humans and agents read from one source; each file is a concept. The gem does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown.

The package, end to end:

Over a bundle the gem gives you the okf command-line tool (the library API is also usable in-process). Each capability below links to the concept that documents it: this gem's own knowledge is an OKF bundle, so you can read its design in the format it defends.

[!TIP] Browse the gem as knowledge, not just docs. This README is the front door; the depth lives in the .okf/ bundle this repo ships. Start at the overview, then follow the graph into the capabilities (what it does), the design constraints (why it stays this light), and the format itself (what it operates on). Run okf server .okf to walk the same bundle as an interactive graph.

It is deliberately light so it runs on the Ruby your OS already ships:

• works on every Ruby since 2.4, the same floor as rack, its core dependency;
• only two runtime dependencies: rack (the server is a mountable Rack app) and webrick (unbundled from Ruby in 3.0);
• no ActiveSupport, no build step, no JavaScript toolchain — the design constraints that hold this line are enforced by tests.

That range is not aspirational: CI runs the full test suite and RuboCop on every one of these on each push.

Why OKF

Project knowledge (why a service exists, what a metric really measures, the reasoning a schema encodes) lives scattered across wikis, code comments, and whoever happened to be in the room, and an agent re-derives it every session. OKF gives it one durable, diffable home, versioned next to the code it describes and read from the same file by people and agents alike. OKF is an open, vendor-neutral format (Google Cloud, 2026); this gem is the Ruby-native way to work with it.

Knowledge already has several homes near an agent, and each holds a different thing. None of the others is built for curated, durable team knowledge:

The last two rows are this gem's job. Scaling past one context window is progressive disclosure — okf index reads the map, okf search pulls only the concepts a task needs, so the bundle is never loaded whole. And drift never hides here: the other homes have no detector, but okf validate and lint turn a bundle's drift into findings you can gate on in CI.

What a bundle looks like

A bundle is just a directory; each concept is one Markdown file whose path is its id. This repo documents itself in OKF, so the tree below is real:

.okf/
├── index.md                       # progressive-disclosure map (root carries okf_version)
├── log.md                         # ISO-dated change history, newest first
├── overview.md
├── format/frontmatter.md
├── model/graph.md
└── capabilities/graph-server.md   # one concept = one file

The only hard requirement is YAML frontmatter with a non-empty type; everything else is optional and tolerated when missing. A concept (here the real capabilities/graph-server.md, body trimmed) reads:

---
type: Capability
title: Interactive graph server (server)
description: A self-contained HTML knowledge graph served over HTTP, and a mountable Rack app.
resource: lib/okf/server/app.rb
tags: [server, graph, rack, diagram]
timestamp: 2026-07-11T12:00:00Z
---

# Overview

`okf server` boots an interactive view of the [graph](../model/graph.md) …

That bundle is this gem's own documentation. Clone the repo and run okf server .okf to browse it as the graph diagrammed at the top of this file.

Installation

In Claude Code, the plugin is the fastest path: two commands install the whole toolchain (skill, /okf:gem, and the curation hook). See Claude Code plugin. Everywhere else, install the gem:

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

From a ch