Your first bundle

Pick the five questions people keep asking

Do not start with a migration. Start with the five things your team re-explains every month: why a service exists, what a metric counts, the decision that looks wrong but was deliberate, the runbook everyone asks for, the table nobody dares to touch. Each becomes one file.

Write the first concept

Create a folder (call it docs/, knowledge/, .okf/, anything) and one file per concept. Only type is mandatory:

---
type: Decision
title: Payment id is the dedup key
description: Why orders deduplicate on payment_id, not order_id.
tags: [billing, incident]
timestamp: 2026-07-13T12:00:00Z
---

# Overview

During the 2023 double-charge incident we found order_id regenerating on
retry. payment_id is stable across retries, so [orders](/tables/orders.md)
deduplicates on it. Changing this breaks revenue reports.

That link to /tables/orders.md is allowed to be broken. The spec tolerates it, and the tooling turns it into your backlog.

Validate early

okf validate docs/

Errors at this stage are almost always a missing frontmatter block or an empty type; the conformance model lists everything that can actually fail. Warnings are fine, keep going.

Add the maps when the folder earns them

Once a directory holds a handful of concepts, give it an index.md (the templates page has the scaffold; the root one carries okf_version: "0.1"). Add a log.md and date your changes. These two files are what make the bundle navigable for someone (or some agent) who was not there when it was written.

Let lint write your backlog

okf lint docs/

The findings are the to-do list: missing concepts ranked by how many places link to them, stubs worth expanding, files nobody can reach. Work the list, or hand it to the agent skill and review the PRs. When someone asks what the graph looks like:

okf server docs/

Make it stick

Two habits keep a bundle alive: run curate (or validate + lint) whenever the knowledge changes, and wire the checks into CI so drift shows up as a finding instead of a surprise. In Claude Code, the plugin does the first habit for you, after every edit.