Architecture
Deliberately boring engineering, enforced by tests.
The core/shell split
Every file in the gem is either pure (the model, the graph, the validator, the linter: no disk, no stdio, no side effects) or shell (the CLI, the server, the on-disk handles: the only layers that touch the world). The boundary is not a convention, it is a test: the suite fails if a pure file names a shell class or reaches for File, Dir, or stdio. That is what makes the library API safe to embed: the analysis you call in-process is incapable of touching your filesystem.
The Ruby 2.4 floor
The gem runs on every Ruby since 2.4, the same floor as rack, its core dependency. The point is not nostalgia: it is running on the Ruby an OS already ships, without asking anyone to install a language first. CI runs the full suite on every supported Ruby, 2.4 through current stable, on each push, so the floor is tested, not aspirational.
Exactly three runtime dependencies
rack (the server is a mountable Rack app), webrick (unbundled from Ruby in 3.0), and minifts (the pure-Ruby full-text engine behind the opt-in okf search --engine index, with no dependencies of its own and the same 2.4 floor). No ActiveSupport, no parser gems, no HTTP clients. A knowledge tool earns trust by being boring: fewer dependencies means fewer reasons the gem you installed two years ago stops working today.
No build step
The interactive graph is one ERB template with inline CSS and JavaScript; the only external code it loads is Cytoscape, marked, and DOMPurify from a CDN, with Mermaid, Panzoom, and MiniSearch lazy loaded on first use (see the trust boundary). There is no bundler, no node_modules, no asset pipeline. What gem install okf puts on disk is the entire product.
The gem documents itself in OKF
The repository carries a real bundle at .okf/: the capabilities, the design constraints on this page, and the format concepts, all as concepts with cross-links. Clone it and run okf server .okf to browse the gem's design as a graph, or read it on GitHub. Dogfooding keeps the tooling honest: every release is validated and linted against its own knowledge base.
What this buys you
Constraints compound into a promise: a bundle you author today, and the tool you author it with, still work unchanged years from now, offline, on the Ruby you already have. For a knowledge base, longevity is the feature.