Ruby, now

One repo, two gems that version together: okf-html (the pure-Ruby format core — serializer, vocabulary, templates; no Rails, no I/O) and okf-html-rails (a mountable engine that wires the core into a host app). Reference gem v0.1.4, tracking spec draft v0.1.

# Gemfile — one repo, two gemspecs
gem "okf-html",       git: "https://github.com/br3nt/okf-html.git",
                       glob: "okf-html/*.gemspec"
gem "okf-html-rails", git: "https://github.com/br3nt/okf-html.git",
                       glob: "okf-html-rails/*.gemspec"

Hosts go through the Repository facade — never hand-write heads, slugs, or rev mirrors. This exact snippet produced the note at the top of the page:

require "okf/html"

repo = OKF::Repository.new(store: OKF::Store::Memory.new)
note = repo.create(
  title: "Sourdough Starter",
  content: %(<p>Feed daily. See <a rel="related" href="/n/bread">bread</a>.</p>),
  tag_names: ["baking", "bread"]
)
puts repo.store.read(note.uuid)   # => the document shown above

In Rails, include the container concern in whatever owns notes and get a scoped repository for free:

class WorkspaceNode < ApplicationRecord
  include OKF::Container
end

node.okf.create(title: "Idea", content: "<p>…</p>", tag_names: ["draft"])
node.okf.find(uuid_or_slug)        # => OKF::Note

Any other language

OKF/HTML is a format, not a framework. Anything that can parse HTML can read and write it — Python, JS, Go, Rust, whatever. Two artefacts get you there without reading Ruby:

• SPEC.md — the format itself: heads, the link graph, rev mirrors, collections, vocabulary, templates, the reconciler, and a conformance checklist (reader / writer / reconciler).
• fixtures/ — language-neutral test vectors, hand-written from the spec and executed against the Ruby implementation to confirm the expected output. render.yml gives attribute bags and the exact HTML a conforming renderer must emit; parse.yml gives stored documents and the fields a parser must extract. Compare rendered HTML as an exact string, including the final newline.

Bring up a port by making render.yml pass, then parse.yml. A case added to the fixtures adds coverage to the reference suite automatically, so the vectors and the implementation can't drift apart.

llms.txt

A short manifest pointing at the spec, the implementer and hypermedia guides, the agent skill, and the conformance fixtures — the map an agent reads first.

Machine-readable spec

SPEC.md is written to be followed literally; the fixtures are executable ground truth an agent can check its output against.

Agent skill

An okf-html skill (.claude/skills/okf-html/ in the repo) teaches an agent to author and manage notes — typed links, collections, templates, vocabulary — as plain HTML.

Hypertext as the API

The engine leans on HTML as the wire format end to end: notes are documents, and the editor and graph ship as no-build components. HTML is what crosses every boundary.