okf-gem

Website  ·  Live demo  ·  Claude Code plugin

okf-gem — okf on RubyGems — reads, validates, lints, and serves
Open Knowledge Format (OKF) v0.1 bundles: directories of Markdown files with YAML frontmatter that humans and agents read from one source. It does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown. Each file is a concept; a directory of them is a bundle.

Quick start. One skill, one command, a curation hook, and a CLI that
validates, lints, indexes, and serves your Markdown as a graph. In Claude Code,
add the plugin and let it set everything up: /plugin marketplace add serradura/okf-gem, then /plugin install okf@okfgem, then /okf:gem. On the
command line: gem install okf, then okf validate <dir>.

Here is what it is able to do:

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 row is this gem's job. The other homes have no detector, so their
drift stays invisible; a bundle's drift shows up as findings you can gate on.

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 checkout, this builds the gem and installs it into your Ruby environment,
putting the okf command on your PATH:

bundle exec rake install

Command line

okf validate  <dir> [--json]                            # check OKF v0.1 conformance (§9)
okf lint      <dir> [--json] [--fail-on warn] [...]     # report curation-quality issues
okf loose     <dir> [--json]                            # list files with no graph links, by folder
okf index     <dir> [--json] [--area A] [--no-body]     # progressive-disclosure map (§6): bodies, rollups, listings
okf server    <dir> [-p PORT] [--bind ADDR] [...]       # serve the interactive graph over HTTP
okf graph     <dir> [--json] [--minimal] [--no-body]    # print the knowledge graph
okf catalog | files | tags | types | stats  <dir> [--json]   # the browser views, on the CLI
okf skill     <dest> [--here] [--force]                 # install the companion agent skill
okf --version

Exit codes: 0 success, 1 non-conformant bundle (or a lint --fail-on
threshold crossed), 2 usage error.

$ okf validate docs
OKF v0.1 conformance — docs
  concepts: 37   index.md: 10   log.md: 1
  ! warn  features/link-suggestions.md: cross-link target not found: `/graph-view.md` (tolerated under §5.3)
  …
  ✓ conformant (33 warning(s))

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

The graph server on this repo's own .okf bundle, with the
capabilities/graph-server concept selected. Try it live at
demo.okfgem.com.

graph and server are best-effort (§9): a file with invalid frontmatter is
skipped (and noted on stderr), not fatal, so one bad file never breaks the rest.
The graph server concept walks the request
flow and endpoints; the server trust boundary below
explains how the page handles a bundle you did not author.

lint (the curation linter) reports curation
quality (reachability, backlog, completeness, freshness, provenance, and hygiene)
separately from validate. It is advisory: it exits
0 even with findings unless you opt into gating with --fail-on warn.

$ okf lint docs
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
    ! warn  features/index.md: index links to missing concept `../../CHANGELOG.md`
  Completeness
    · info  features/bundles/entry-editor.md: missing recommended field: description
  Hygiene
    ! warn  link-suggestions.md: reference-style link `[:approved_ids]` has no matching definition (an invisible broken link)

  ⚠ 3 warn, 31 info

loose lists the files that float in the graph: concepts with no cross-links
in or out (graph degree 0), grouped by folder. It is a curation lens over
lint's unlinked check, distinct from orphan. An index.md listing makes a
file reachable (not an orphan) but is not a graph edge, so a listed file
can still be loose. A loose file may be fine: a terminal leaf like a backlog
item is loose by design. loose surfaces the set for you to judge and
always exits 0.

Agent skill

The gem carries the companion OKF agent skill:
a SKILL.md plus reference
and template files that teach a coding agent to author, maintain, and consume OKF
bundles and to drive the commands above. Because the skill ships inside the gem,
installing the gem already puts the skill on your machine, and the skill's
CLI reference can never drift from the executable it was released with.
Using Claude Code? The plugin below installs this same
skill plus a post-edit curation hook.

The skill routes a small set of verbs. In Claude Code they run as /okf:gem <verb>; used standalone, the skill infers the verb from your request.

Point it at your agent's config directory (or its skills directory) and the tree
settles in its own skills/okf/ folder, so a shared skills directory never gets
the files loose:

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

The destination is required (no default). The skill lands in <dest>/skills/okf,
unless <dest> already ends in skills (→ <dest>/okf) or okf (used as-is).
Pass --here to paste the tree straight into <dest>, wherever it is. The
resolved directory must be empty unless you pass --force, so a customized skill
is never clobbered.

Library

The gem (the library API) is two layers: pure
in-memory data (OKF::Concept, OKF::Bundle)
you build, interrogate, and analyze with no disk involved, and on-disk
handles (OKF::Concept::File, OKF::Bundle::Folder) that add
load/save/reload/delete, an "ActiveRecord for the filesystem".

Pure, in-memory (no disk)

Build knowledge straight from data, with no markdown round-trip, and run every
feature against it. This is the surface an embedding app (e.g. a Rails store)
uses to reuse the gem over knowledge it already holds as records:

require "okf"

concept = OKF::Concept.new(
  path: "tables/orders.md",
  frontmatter: { "type" => "BigQuery Table", "title" => "Orders" },
  body: "Joined with [customers](/tables/customers.md).\n"
)

concept.id                       # => "tables/orders"
concept.links                    # => ["/tables/customers.md"]  (spec §5 cross-links)
concept.citations                # => [...]                     (spec §8 # Citations)
concept.external_links           # => [...]                     (URLs / mailto:)
concept.to_markdown              # => String  (inverse of OKF::Markdown::Frontmatter.parse)
concept.lint                     # => OKF::Bundle::Linter::Report  (the concept-scoped checks)

bundle = OKF::Bundle.new(concepts: [ concept ])   # also: reserved:, unparseable:
bundle.validate                  # => OKF::Bundle::Validator::Result  (spec §9 conformance)
bundle.lint                      # => OKF::Bundle::Linter::Report     (curation quality)
bundle.graph                     # => OKF::Bundle::Graph              (#nodes, #edges, #to_h)

On disk

OKF::Bundle::Folder reads a directory into a pure bundle and materializes one
back; OKF::Concept::File is a single-file handle:

folder = OKF::Bundle::Folder.load("docs")
folder.bundle                    # => OKF::Bundle  (the pure bundle it read)
folder.concepts                  # => [OKF::Concept]  (reserved files excluded)
folder.validate; folder.lint; folder.graph   # delegate to the pure core
folder.concept("tables/orders")  # => OKF::Concept::File
OKF::Server::App.new(folder)     # => a Rack app: the interactive graph server

# build in memory, then write it out (validates §9 before publishing):
OKF::Bundle::Folder.new(bundle: bundle, root: "out/dir").save

file = OKF::Concept::File.read(root: "docs", path: "tables/orders.md")
file.concept                     # => OKF::Concept (pure)
file.save; file.delete; file.reload

The lower-level pieces are usable on their own too: OKF::Bundle::Validator.call(bundle),
OKF::Bundle::Linter.call(bundle, min_body: 50), OKF::Bundle::Graph.build(bundle),
OKF::Markdown::Frontmatter.parse(markdown).

Conformance model

validate (the conformance validator) implements
the spec's §9 conformance definition
exactly. There are three hard conditions, all errors:

• §9.1 every non-reserved file has a parseable YAML frontmatter block;
• §9.2 every such block has a non-empty type;
• §9.3 every index.md/log.md present follows §6/§7: a nested index.md
  has no frontmatter, a root index.md carries only okf_version, and log.md
  date headings are ISO YYYY-MM-DD.

Everything the spec marks as soft guidance is a warning and never makes a
bundle non-conformant: missing recommended fields, non-list tags, an unparseable
timestamp, and broken cross-links (§5.3), which consumers MUST tolerate.
OKF::Bundle::Folder#save validates before publishing, so it never writes a
bundle that fails §9.

Curation model (lint)

validate asks "is this §9-conformant?" and is forbidden by §9 to reject for
broken links or missing optional fields. lint asks the complementary question,
"is this well-curated, navigable, trustworthy?", over exactly those tolerated
things. The two stay separate: lint has its own OKF::Bundle::Linter and
report, never emits conformance errors, and is advisory unless you pass
--fail-on warn.

Checks span six categories: reachability (orphans, not-in-index, disconnected
islands, unlinked), backlog (demand-ranked missing concepts, broken index entries),
completeness (stubs, missing title/description/timestamp), freshness
(--stale-after), provenance (uncited external claims, broken citations,
spec §8), and hygiene (duplicate titles, unused/undefined reference links,
self-links). Select with --only/--except; --json emits the full report as JSON.

Two loop concerns from the format's own guidance, contradictions and semantic
staleness, need to understand meaning and are not computed here; lint --json
is the structured input an agent consumes to reason about those.

Server trust boundary

[!NOTE]
The graph page defends against a bundle that carries active content in two
places. It escapes any graph data inlined into the page (< becomes <),
which keeps that data from breaking out of its <script>. And it fetches each
concept body on demand, then runs marked's HTML output through
DOMPurify before it reaches the DOM, so
a script or event handler hidden in a Markdown body is stripped rather than
executed. Descriptions are escaped on the server.

That covers the paths that could run code. The page still loads Cytoscape,
marked, and DOMPurify from a CDN and renders whatever links and diagrams a body
contains, so treat an unfamiliar bundle the way you would treat any document
from a source you do not know.

The server trust boundary concept has the
full write-up: the two data paths, what sanitizing does, and what it leaves to
your judgment.

Claude Code plugin

This repository doubles as a Claude Code plugin marketplace, so the whole
toolchain installs with two commands inside Claude Code:

/plugin marketplace add serradura/okf-gem
/plugin install okf@okfgem

The plugin carries three pieces:

The hook stays silent outside bundles, and when the CLI is missing it suggests
/okf:gem once per session instead of failing on each edit. It is config-free to
switch off: set OKF_CURATE_DISABLED=1 to turn it off, OKF_CURATE_QUIET=1 to
keep the findings but drop that suggestion, or drop an <!-- okf-disable -->
comment into a file to skip curation for that one.

Prefer no plugin? gem install okf && okf skill .claude installs the skill
alone, and the skill itself instructs the agent to run the same checks after
editing a bundle.

Development

bin/setup               # install dependencies
bundle exec rake        # tests + RuboCop (what CI runs)
bundle exec rake test   # just the test suite
ruby -Ilib exe/okf validate <dir>   # run the CLI from a checkout

The suite runs on every supported Ruby; to check the 2.4 floor locally:

docker run --rm -v "$PWD":/app -w /app ruby:2.4 \
  bash -c "bundle install && bundle exec rake test"

Contributing

Bug reports and pull requests are welcome on GitHub at
https://github.com/serradura/okf-gem. This project is intended to be a safe,
welcoming space for collaboration, and contributors are expected to adhere to
the code of conduct.

License

The gem is available as open source under the terms of the
Apache License 2.0 (see
LICENSE.txt). The Open Knowledge Format specification bundled with the skill
is authored by Google Cloud Platform and included under its own Apache-2.0
license, Copyright (c) Google LLC. See NOTICE and
lib/okf/skill/reference/APACHE-2.0.txt.

okf-skills by Marco Boffo, a Python
OKF toolkit for Claude Code with a feature-rich interactive graph view, was an
early inspiration for this gem's Claude Code plugin and for the knowledge-as-code
comparison in Why OKF. okf-gem takes a different shape: a Ruby-native
gem built around the okf CLI and an embeddable library.