# okf-gem

> okf-gem is the complete toolkit for the Open Knowledge Format (OKF), an open, vendor-neutral format for project knowledge: directories of Markdown files with YAML frontmatter that humans and agents read from the same source. The gem ships an agent skill that authors and curates bundles, a CLI that validates and lints them, and a live knowledge-graph server. It runs 100% local on every Ruby since 2.4.

The full documentation as one plain-text file: https://okfgem.com/llms-full.txt

## Start here

- [Getting started](https://okfgem.com/docs/getting-started/): Install okf-gem, validate your first directory, and open the live knowledge graph in under five minutes. Runs on every Ruby since 2.4 with three dependencies.
- [Run with Docker](https://okfgem.com/docs/docker/): Run every okf command without installing Ruby. The official image bundles the CLI and the graph server; mount your bundle at /data and go. Published multi-arch on ghcr.io.
- [Why OKF](https://okfgem.com/docs/why-okf/): Project knowledge lives scattered across wikis, agent memory, and people's heads. The Open Knowledge Format gives it one durable, diffable home in git, checked by tooling.
- [Bundle anatomy](https://okfgem.com/docs/bundle-anatomy/): What an OKF bundle is made of: concept files with YAML frontmatter, plain Markdown cross-links that become graph edges, index.md maps, and a dated log.md history.
- [The OKF v0.1 specification](https://okfgem.com/docs/spec/): The Open Knowledge Format v0.1 specification: bundle structure, concept documents, cross-linking, index and log files, citations, and the conformance definition.

## Guides

- [Your first bundle](https://okfgem.com/docs/guides/first-bundle/): A guided path from an empty folder to a healthy knowledge graph: five concepts, honest frontmatter, cross-links, an index, and the checks that keep it that way.
- [Gate knowledge drift in CI](https://okfgem.com/docs/guides/ci/): Wire okf validate and okf lint into a pipeline so a broken or rotting bundle fails a check instead of surprising the next reader. Exit codes and a GitHub Actions example.
- [Mount the graph in Rails](https://okfgem.com/docs/guides/rails/): The interactive knowledge graph is a Rack app, so it mounts inside a Rails application under any prefix, behind your own authentication. One bundle or a hub of many, auth patterns, the trailing-slash mount contract, and what updates live.

## Agent skill

- [The OKF agent skill](https://okfgem.com/docs/skill/): The okf skill: a SKILL.md plus playbooks, references, and templates that ship inside the gem and teach any coding agent to author, curate, search, and consume OKF bundles.
- [search: retrieve without reading the whole bundle](https://okfgem.com/docs/skill/search/): How the skill answers a question from a bundle: ingest the index map, decide where to look, cut across with okf search, and read only the winning bodies.
- [orient: pick the next move](https://okfgem.com/docs/skill/orient/): How the skill answers 'what should I do?': it reads the bundle's state through the CLI, then recommends the highest-value next verb without running one.
- [produce: create or extend a bundle](https://okfgem.com/docs/skill/produce/): How the skill creates or extends an OKF bundle: model concepts from code, docs, or tribal knowledge, then walk the closeout gate before finishing.
- [migrate: OKFy existing docs in place](https://okfgem.com/docs/skill/migrate/): How the skill converts documentation you already have into a conformant OKF bundle: frontmatter and reserved files added, every body kept verbatim, with the validator as the worklist.
- [maintain: sync knowledge with reality](https://okfgem.com/docs/skill/maintain/): How the skill catches a bundle up after the code or docs change: find every affected concept, update it, and verify that nothing drifted silently.
- [consume: use a bundle as context](https://okfgem.com/docs/skill/consume/): How the skill uses a bundle as task context: orient on the index and log, follow links into what the task needs, and write back what the work teaches.
- [curate: the structural upkeep cycle](https://okfgem.com/docs/skill/curate/): How the skill runs the full curation cycle over a bundle: measure with validate, lint, and loose, fix what hurts readers most, and re-measure the result.
- [refine: restructure the bundle to get the most from OKF](https://okfgem.com/docs/skill/refine/): How the skill optimizes a bundle's shape rather than its content: measure tag locality and hub origins with the CLI, judge where knowledge should live, and propose the moves. Refine changes where knowledge lives, never what it says, and it proposes rather than auto-applies.
- [doctor: install and verify](https://okfgem.com/docs/skill/doctor/): How the skill installs and verifies the okf CLI on whatever Ruby the system already ships, then checks the repo's bundle and reports on its health.

## CLI · judge

- [The okf CLI](https://okfgem.com/docs/cli/): One executable that judges, reads, and serves OKF bundles: conformance and curation gates, ranked search, the read views, a live graph server, and a skill installer.
- [okf validate](https://okfgem.com/docs/cli/validate/): Check OKF v0.1 conformance exactly as the spec defines it (section 9): hard errors for what must hold, warnings for everything the spec tolerates. Exit codes ready for CI.
- [okf lint](https://okfgem.com/docs/cli/lint/): Report curation quality across six categories (reachability, backlog, completeness, freshness, provenance, hygiene) without ever failing conformance.
- [okf loose](https://okfgem.com/docs/cli/loose/): List the concepts with no cross-links in or out, grouped by folder, so you can decide which files should join the graph and which are leaves by design.

## CLI · read

- [okf search](https://okfgem.com/docs/cli/search/): Ranked text retrieval across a bundle: case-insensitive terms, Ruby regexps, or an opt-in BM25+ full-text index over titles, ids, tags, types, descriptions, and bodies, with filters, projections, and context snippets.
- [okf dirs](https://okfgem.com/docs/cli/dirs/): List a bundle's directories with the number of concepts living directly in each, root first and the total last. The small, shape-first read that stays legible on a bundle of any size, with --dir for subtree counts and --depth to walk the tree one level at a time.
- [okf index](https://okfgem.com/docs/cli/index/): Print the progressive-disclosure map from spec section 6: every directory with its index body, type and tag rollups, child pointers, and concept listing.
- [okf catalog](https://okfgem.com/docs/cli/catalog/): List every concept with its full metadata (type, status, tags, timestamp, link degree, description), grouped by directory and filterable by type, directory, or tag.
- [okf files](https://okfgem.com/docs/cli/files/): Print the bundle's folder tree, each concept's filename and title grouped by directory, the fastest way to see how the knowledge is laid out on disk.
- [okf tags](https://okfgem.com/docs/cli/tags/): List every tag with the concepts that carry it, ordered by count, and regroup by type or directory to see which themes connect the bundle and which scatter.
- [okf types](https://okfgem.com/docs/cli/types/): List every concept type with the concepts that carry it, ordered by count descending, the quickest read on what kinds of knowledge a bundle holds.
- [okf stats](https://okfgem.com/docs/cli/stats/): Print bundle rollups (concept, directory, type, cross-link, and distinct-tag totals plus per-type and per-directory breakdowns) to size any bundle in one command.
- [okf graph](https://okfgem.com/docs/cli/graph/): Print the knowledge graph as nodes and edges, with JSON dumps at three sizes (full, no-body, minimal) for piping into analysis or planning a traversal.

## CLI · serve & setup

- [okf registry](https://okfgem.com/docs/cli/registry/): A persistent, per-user list of bundles: register a directory once, name it @slug from anywhere, and a bare okf server hosts the whole list behind one hub.
- [okf server](https://okfgem.com/docs/cli/server/): Serve the bundle as an interactive graph over HTTP: nodes colored by type, sanitized live markdown panels, filters, and search, from one local command.
- [okf render](https://okfgem.com/docs/cli/render/): Write the interactive graph as one static, self-contained HTML file with the whole bundle baked in, so it hosts on GitHub Pages or anywhere a server cannot run.
- [okf skill](https://okfgem.com/docs/cli/skill/): Install the companion agent skill that ships inside the gem, so your coding agent learns to author, curate, and consume OKF bundles with the same CLI.

## Reference

- [Conformance model](https://okfgem.com/docs/conformance/): How okf validate implements the OKF spec's section 9 exactly: three hard errors, everything else a warning, and why broken links can never fail a bundle.
- [Curation model](https://okfgem.com/docs/curation/): The sixteen checks behind okf lint, grouped in six categories: reachability, backlog, completeness, freshness, provenance, and hygiene. Advisory by default, gateable in CI.
- [Ruby library API](https://okfgem.com/docs/library/): Embed okf-gem in your own Ruby: a pure in-memory core (Concept, Bundle, Graph) with no disk involved, plus on-disk handles that read and atomically write bundles.
- [Graph server](https://okfgem.com/docs/graph-server/): The interactive knowledge graph okf server boots: live-from-disk concept bodies, the authored index map as a drawable layer, a nested file tree, ranked full-text search, filters, and a sanitized rendering pipeline.
- [MCP server](https://okfgem.com/docs/mcp/): The okf-mcp gem serves your registered bundles over the Model Context Protocol: ten read-only tools, concepts as attachable resources, and retrieval prompts, for Claude Desktop, Claude Code, or any MCP-capable host.
- [Templates](https://okfgem.com/docs/templates/): The four scaffolds the OKF skill ships: a concept file, nested and root index.md maps, and the dated log.md. Copy them as-is; the placeholders explain themselves.
- [Architecture](https://okfgem.com/docs/architecture/): The constraints that keep okf-gem dependable: a test-enforced core/shell split, a Ruby 2.4 floor, exactly three runtime dependencies, and no build step anywhere.
- [Claude Code plugin](https://okfgem.com/docs/plugin/): Install the whole OKF toolchain inside Claude Code with two commands: the canonical skill, the /okf:gem command, and a deterministic post-edit curation hook.

## Project

- [Changelog](https://okfgem.com/docs/changelog/): Every okf gem release with what changed: the CLI, the graph server, the agent skill, and the Claude Code plugin.

## Blog

- [Your docs are already the bundle: /okf migrate](https://okfgem.com/blog/okf-migrate-existing-docs/): Adopting a knowledge format usually means rewriting what you already wrote, which is why adoption stalls. /okf migrate, new in 1.7.0, adopts your existing Markdown in place: frontmatter and reserved files added, every body kept verbatim. The links you wrote years ago become the graph on day 0, and produce, search, and maintain compound from there.
- [Search every bundle at once: okf 1.10.0](https://okfgem.com/blog/okf-search-every-bundle/): The okf CLI has been able to search across bundles since 1.8.0. The page you actually read them in could not. okf 1.10.0 gives the hub a full-text search over every bundle it hosts, ranked by one shared index rather than by stapling per-bundle lists together, and moves the registry into the page it manages. It also adds a refine verb to the skill, the inbound ranking that backs it, and an extension point that lets any gem add a verb.
- [Find your way around a big bundle: okf 1.11.0](https://okfgem.com/blog/okf-1-11-0/): A bundle's map grows with its directory tree, and past a point nobody reads it whole. okf 1.11.0 adds okf dirs, a --depth cut on index and dirs, and a --dir filter shared across the read verbs, so orientation costs what you choose to spend. It also builds a served bundle's search index once at boot instead of rebuilding it on every request.
- [Bundles you can group, a graph you can read: okf 1.12.0](https://okfgem.com/blog/okf-1-12-0/): okf 1.12.0 lets a registry live in your repo and travel with it, gives a named group of bundles a single slug you can search and serve, and teaches the graph page to open on a readable spine instead of a wall of arrows. It also adds okf graph --traffic, which reads cohesion against coupling one directory at a time.
- [The map was always in the bundle. Now the graph draws it.](https://okfgem.com/blog/okf-graph-index-layer/): Every OKF bundle carries an authored index.md per directory, and the graph page could only show them inside file-tree mode. okf 1.9.0 makes the index map a layer you can draw over any layout, with authorship shown as form. The file tree nests, the Indexes tab dissolved into a toggle, and a first-time reader is finally told where to start.
- [Host the graph anywhere: okf render](https://okfgem.com/blog/okf-render-static-graph/): okf server draws your bundle as a live graph, but a server is a process that needs somewhere to run. okf render, new in 1.6.0, writes that same page as one static HTML file with the whole bundle baked in, so the graph hosts on GitHub Pages or anywhere static files go. The same release ships the official Docker image.
- [A 50x speedup you cannot spend](https://okfgem.com/blog/okf-faster-search-off-by-default/): minifts is a pure-Ruby port of MiniSearch, and okf 1.9.0 makes it an opt-in search engine. It sustains 44 to 56 times the linear scan's query throughput and still loses end to end, because a one-shot CLI pays the index build for a single question. This is the measurement, what the index costs when you do want it, and the sidecar that would change the arithmetic.
- [Search you can swap: okf 1.9.0](https://okfgem.com/blog/okf-pluggable-search/): okf 1.9.0 lets you choose how search runs. A new BM25+ full-text engine answers queries 44 to 56 times faster than the default and still ships switched off, because a CLI that exits pays the index build for a single question. The graph page also draws the authored index map as a layer, and the agent skill takes registry refs as first-class targets.
- [Your bundles get names: okf 1.8.0](https://okfgem.com/blog/okf-registry-many-bundles/): okf 1.8.0 adds a persistent registry: register a bundle once and every verb reaches it as @slug from anywhere, a bare okf server hosts them all behind one hub, and search spans them in one query. The graph page grew up too, with a command palette in every mode, a shortcut sheet, and one layout from phone to desktop. And a machine-level list of named bundles is exactly the groundwork an MCP future stands on.
- [Your bundles, served to any agent: okf-mcp 1.0.0](https://okfgem.com/blog/okf-mcp-1-0-0/): okf-mcp 1.0.0 serves your OKF bundles over the Model Context Protocol: ten read-only tools, answers bounded for a context window, and bodies that always read live from disk. It rides okf 1.13.0, which hardens every read surface against symlinks that point outside the bundle.
- [Run okf anywhere: the Docker image](https://okfgem.com/blog/run-okf-with-docker/): okf is pure Ruby, but the Ruby on the box is not always yours to choose. The official Docker image carries the whole CLI, so validate, lint, search, and the live graph run with nothing to install. Multi-arch, built from source, on ghcr.io.
- [Should your team adopt OKF?](https://okfgem.com/blog/should-your-team-adopt-okf/): The honest evaluation of the Open Knowledge Format for an engineering lead deciding adoption for other people: what it costs in hours, what happens when the author leaves, why it beats the wiki you already ignore, whether it survives a tool change, and the one thing it does not do. Framed on token cost, the number the budget and the engineers both read.
- [Your agent is reading four times more than it needs to](https://okfgem.com/blog/retrieve-dont-dump/): Most agent setups hand the whole project over on every question. okf answers by retrieving instead: a map, a search, and one file. A test in its suite fails the build if that path ever costs more than a quarter of handing the bundle over whole, and on a real project a question lands at a fortieth. The token-cost case for retrieval over dumping, and the one limit it does not cross.
- [What is the Open Knowledge Format?](https://okfgem.com/blog/what-is-okf/): OKF is an open, vendor-neutral format for keeping project knowledge as Markdown + YAML, versioned with the code and readable by people and agents from the same file. How a bundle works, and how to start one.
- [Why I built okf-gem](https://okfgem.com/blog/why-okf-gem/): Standards are what make scale possible. How my agent workflow evolved from spec frameworks to a well-documented harness, and why that led to a complete OKF toolkit: skill, CLI, Ruby objects, and a mountable graph. 100% local.

## Project

- [okfgem.com](https://okfgem.com/): product landing page
- [Live demo](https://demo.okfgem.com): a real OKF bundle served as an interactive graph
- [Claude Code plugin](https://claude.okfgem.com): skill + /okf:gem + curation hook
- [GitHub](https://github.com/serradura/okf-gem): source, issues, marketplace
- [RubyGems](https://rubygems.org/gems/okf): gem install okf