Bundle anatomy

A bundle is a directory

No database, no manifest, no build step. A bundle is a folder; each concept is one Markdown file whose path is its id. okf-gem's own repository documents itself in OKF, so this tree 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

A concept is Markdown + frontmatter

The only hard requirement is YAML frontmatter with a non-empty type. Everything else is recommended and tolerated when missing:

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

# Overview

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

The fields carry distinct jobs: type classifies (Service, Metric, Decision, Playbook, whatever vocabulary fits your domain), description is the one-line summary every listing reuses, resource bridges the concept to the asset it describes (a file, a table, a URL), tags cut across the folder structure, and timestamp feeds freshness checks. The templates page has ready scaffolds.

Links are edges

Concepts reference each other with plain Markdown links: absolute from the bundle root (/tables/customers.md) or relative (../model/graph.md). Files are nodes, links are edges, so the knowledge graph emerges from the writing itself; you never declare it. Broken links are tolerated by the spec (section 5.3): a link to a concept nobody wrote yet is demand, not an error, and okf lint ranks those missing targets as a backlog.

The reserved files

Two filenames are structural rather than conceptual:

• index.md, one per directory that wants a map. It lists what lives there and where to descend next, which is how a bundle stays useful past one context window (the spec calls it progressive disclosure; okf index is its read view). A nested index.md has no frontmatter; the root one carries only okf_version.
• log.md, the bundle's own change history: ISO-dated headings, newest first, one bullet per creation, update, or deprecation.

Citations

Claims that come from somewhere carry a # Citations section with numbered links (spec section 8). okf lint flags external claims without citations and citations that point nowhere.

Read it as a graph

Everything above is plain text, so it diffs, reviews, and greps. When you want the shape instead of the words: okf server renders the live graph, okf graph prints the raw nodes and edges, and okf stats sizes the bundle at a glance.